Skip to content

Eefje Bug/Feature Intake Process (v1)

Status: active (revised 2026-11-01, v1.57) Owner: Ivar Created: 2026-04-17

Updated 2026-05-06: intake now runs through the feedback repo

Since 2026-05-06 Eefje reports bugs and feature requests via issue forms in Voorman/freezedesign-feedback β€” no longer via WhatsApp or PDF. The authoritative process description for agents lives in .claude/CLAUDE.md (section "Eefje Intake and Bug Handling"); the operator steps are in the Eefje feedback intake runbook. This document is the longer-form background. Internal work (Ivar/agent-reported, not visible to Eefje) still uses .planning/todos/pending/<slug>.md with status: ready.

Why this document exists

Eefje (the business owner and primary tester) is the only non-technical stakeholder reporting bugs and feature requests on Freeze Design. Historically (pre-2026-05-06) she delivered them via PDF files dropped in the repo root (Foutmeldingen nieuw porduct aanmaken..pdf, Nog meer dingetjes.pdf) and via WhatsApp notes. That is fine for occasional input but breaks down at volume:

  • Items are mixed together (bugs, features, decisions-still-to-make, content)
  • Nothing is versioned against the staging SHA she tested on
  • Duplicate reports can't be detected
  • No audit trail of what was triaged, fixed, or deferred
  • Agents can't pick up work without manual translation

This document defines the intake process and shows how it maps to the existing GSD workflow.

The layered model (since 2026-05-06)

There are two intake tracks. An agent works on exactly one of two sources:

Track 1 β€” Eefje reports (feedback repo, "goedkeuren eerst" since 2026-10-10):

flowchart LR
    A["Eefje: issue form<br/>status:needs-triage"]:::intake --> B["Intake assistant<br/>investigates in the code"]:::plan
    B -->|questions| C["status:awaiting-eefje /<br/>status:awaiting-ivar"]:::plan
    C --> B
    B -->|proposal| D["status:proposed"]:::plan
    D -->|"Ivar: /ready in the intake issue<br/>(this repo, label intake)"| E["status:ready"]:::intake
    E -->|"dagplanning / agent"| F["status:in-progress<br/>PR against staging"]:::exec
    F -->|merge + staging deploy| G["status:retest-pending<br/>(retest comment with SHA)"]:::verify
    G -->|Eefje retests OK| H["Eefje closes the issue"]:::closed
    classDef intake fill:#e0f2fe,stroke:#0284c7;
    classDef plan fill:#ede9fe,stroke:#7c3aed;
    classDef exec fill:#fef9c3,stroke:#ca8a04;
    classDef verify fill:#dcfce7,stroke:#16a34a;
    classDef closed fill:#f3f4f6,stroke:#6b7280;

From Eefje's form to her own close: the assistant investigates and proposes, Ivar says yes with status:ready, an agent builds, the staging deploy triggers the retest.

The intake assistant (.github/intake-agent/AGENT.md in the feedback repo) reacts to every report and reply from Eefje. It looks the bug or wish up in the code and then does one of three things: ask Eefje questions (status:awaiting-eefje), put a technical choice to Ivar (status:awaiting-ivar), or make a proposal and ask Ivar whether it may be built (status:proposed). It builds nothing. Ivar says yes by setting status:ready. Because Eefje can set labels too, status:ready only counts when the last labeled event for it came from Voorman (see .claude/CLAUDE.md, "Goedkeuren eerst"). The assistant's proposal is the scope Ivar approved; an agent that deviates says so in the PR.

Since v1.52 (#843) Ivar's part of a report lives in an intake issue in this repo (label intake, title Intake feedback #<N>: …); Eefje does not see it. The assistant puts its proposal and open points there, Ivar answers there, and a comment /ready by Voorman makes intake-ready.yml set status:ready on the feedback issue (with FEEDBACK_REPO_TOKEN, so on Voorman's name) and close the intake issue; any other answer while the report waits on a technical choice restarts the assistant. Nothing for Ivar or for agents is written in Eefje's issue: no @Voorman, no /ready, no technical detail. Older reports still carry the proposal in the feedback issue itself (replies ending in "πŸ€– Automatische assistent van Freeze Design"). Find the intake issue with:

gh issue list -R Voorman/webshop_freeze_design -l intake --state all \
  --search "in:title \"Intake feedback #<N>:\"" --json number,url

Track 2 β€” Internal work (Ivar/agent-reported, not Eefje-visible):

flowchart LR
    A[".planning/todos/pending/slug.md<br/>status: ready (Ivar)"]:::intake --> B["Dagplanning routine<br/>(ma–vr 03:07) β†’ plan PR"]:::plan
    B -->|"Ivar merges = go"| C["/dagstart β†’ dagbouw session<br/>PR against staging"]:::exec
    C -->|"dagbouw-bewaker: auto-merge<br/>or wacht-op-ivar"| D["staging deploy<br/>todo status: staging"]:::verify
    D -->|"promotion + check on production"| E["todo β†’ done/"]:::closed
    classDef intake fill:#e0f2fe,stroke:#0284c7;
    classDef plan fill:#ede9fe,stroke:#7c3aed;
    classDef exec fill:#fef9c3,stroke:#ca8a04;
    classDef verify fill:#dcfce7,stroke:#16a34a;
    classDef closed fill:#f3f4f6,stroke:#6b7280;

Ready todos are sequenced at night, built by day, and move to done/ only after a check on production.

Feedback issues with status:ready (set by Voorman) go on the same day plan as the ready todos. The planner (.claude/skills/dagplanning/) orders the work, proposes new, split or merged todos on awaiting-decision, and opens a plan PR claude/dagplanning-<date> against staging with the file .planning/dagplanning/<date>.md; it merges nothing. Ivar's merge is the go for the day; /dagstart then starts up to three local dagbouw sessions, one item each. Design: docs/PLAN-dagplanning.md.

Key insight: feedback issues and todos are the intake layer. The GSD milestone/phase/plan system that used to consume them ended with v1.27 (2026-05-03); the day plan replaced it. Raw input (WhatsApp, PDF, verbal, email) is never a task in itself: Ivar or Eefje opens a feedback issue first.

Branch model (since 2026-05-04)

Branch Purpose Deploy target
feature/* of fix/* Active work, one per todo none
staging Integration; auto-deploys to staging.freezedesign.nl staging environment
main Code-of-record; only updated by promotion-PRs from staging after Eefje confirms none directly (production via tagged release only)
vX.Y tags Production releases, on main production environment: scripts/deploy-production.sh creates the tag and dispatches deploy-production.yml (first release v1.26 on 2026-09-04)

Promotion flow: feature β†’ PR against staging β†’ CI green β†’ squash-merge β†’ auto-deploy to staging β†’ Eefje retests β†’ on confirmation, fast-forward or PR staging β†’ main β†’ scripts/deploy-production.sh tags the main commit and runs deploy-production.yml with that tag to ship.

Automation: scripts/release.sh <pr-number> automates the entire flow (merge to staging → wait for staging-deploy → UAT-pause → promotion PR → CI green → fast-forward main to the tested staging SHA). Use --promote-only for staging→main alone, --no-uat to skip the pause (low-risk only, and still only after Eefje's retest), --dry-run to preview. The fast-forward is intentional: main points to exactly the commit that was tested and deployed on staging, and both branches keep the same SHAs. Until 2026-09-26 the script rebase-merged the promotion PR instead; that gave main copies with new SHAs, and the branches drifted apart until promotions got stuck (#335, #337).

Pre-2026-05-04 the project deployed staging from main directly; the CLAUDE.md rule "PR against staging, never main" only matched the infrastructure as of this commit.

How Eefje reports (since 2026-05-06: one channel)

GitHub issue form in Voorman/freezedesign-feedback

  • Dutch issue forms in the dedicated feedback repo (separate from the code repo)
  • The form fields ("Wat ging er mis?", "Wat verwachtte je?") are the source of truth β€” not an agent's own interpretation
  • Status labels drive the workflow: status:needs-triage β†’ assistant: status:awaiting-eefje / status:awaiting-ivar / status:proposed β†’ status:ready (set by Voorman) β†’ status:in-progress (agent) β†’ status:retest-pending (automatic after the staging deploy) β†’ issue closed by Eefje. Older labels (status:needs-clarification, status:awaiting-decision, status:blocked-on-content) still exist and also mean "not for an agent".
  • Fetch the backlog with:
gh issue list -R Voorman/freezedesign-feedback -l status:ready \
  --json number,title,body,labels

WhatsApp, PDF, and email are no longer intake channels. If raw input still arrives that way, Ivar (or Eefje herself) opens a feedback issue first β€” raw input is never a task in itself, and agents never create feedback issues on Eefje's behalf without Ivar's instruction.

The triage step (assistant first, then Ivar in a few minutes per report)

For a feedback issue the intake assistant does the investigation and the first reply; Ivar only decides. The statuses are labels on the feedback issue; for internal work they are frontmatter fields on the todo file:

Kind Example What happens
Clear bug "Footer shows 2025, moet 2026 zijn" Assistant proposes the fix (status:proposed); Ivar sets status:ready
Clear small feature "Logo iets groter" Same: proposal, then status:ready
Ambiguous "De categorie" (incomplete sentence) Assistant asks Eefje (status:awaiting-eefje)
Technical choice Two ways to fix it Assistant asks Ivar (status:awaiting-ivar)
Content delivery "Afbeelding stuur ik per email" Stays open with Eefje; older label status:blocked-on-content
Big feature "Producten van eigen ontwerpen zonder designer" Ivar writes a design doc (docs/PLAN-*.md) and todos; a todo with needs-scoping waits for that scoping session first
Duplicate Already reported Link the issues, close the duplicate
Already fixed She missed it Reply with "dit is al gefixt in vX.Y"

Ivar can also convert input from another channel into a feedback issue himself; agents never open issues on Eefje's behalf.

Todo file format (extends GSD default)

This applies to internal todos (Track 2) β€” Eefje reports live as feedback issues and don't get a todo file. GSD's default todo template is minimal; add these frontmatter fields so todos carry enough context to become phase plans:

---
title: <short descriptive title>
type: bug | feature | content | decision | chore | refactor
status: ready | needs-clarification | awaiting-decision | blocked-on-content | needs-scoping | staging | split | merged | done
severity: blocker | important | nice-to-have   # or minor
area: homepage | designer | product-catalog | admin | checkout | email | infra | frontend | other
reporter: eefje | ivar | agent
reported_via: whatsapp | github | email | pdf | chat-claude
reported_date: YYYY-MM-DD
source: "<verbatim quote from Eefje, or the review/PR/report the todo came from>"
staging_sha_when_reported: <short sha or 'unknown'>
related_todos: []
blocked_by: []
---

Body sections: 1. What Eefje said (verbatim) β€” her exact words, Dutch preserved (omit for internal todos) 2. Ivar's interpretation β€” what this actually means technically 3. Proposed scope β€” smallest change that solves the reported problem 4. Open questions β€” what's unclear, what needs confirmation 5. Definition of done β€” how we'll know it's fixed (from Eefje's perspective)

Statuses and who sets them (.claude/CLAUDE.md, section "Werken op een todo"): ready is Ivar's go and nobody else sets it; awaiting-decision is what the planner, the website check and agents use for proposals; staging is set by the build session when the PR is merged to staging; split / merged come from a merged plan PR (see split_into / merged_into); done (with resolved_date, resolved_pr, resolved_commit) is set after a check on production, and the file moves to .planning/todos/done/ in a chore(todos): <slug> β†’ done (#<PR>) PR. The workflow todo-done-check.yml (scripts/check-done-todos.sh) checks such a PR: the four fields are filled in and resolved_commit is part of the last successful production deploy. A todo without a status counts as needs-clarification.

From todos to the day plan

Every working night the Dagplanning routine reads the ready todos (with every blocked_by slug in done/) and the feedback issues that Voorman set to status:ready, skips anything with an open PR or status: staging, and puts what can be done entirely in the repo on the plan. Work that needs the VPS, DNS, an external account, a secret, a purchase or content from Eefje goes to the "Voor Ivar" section; voor-ivar-lijst.yml collects those lines in a pinned "Voor Ivar" issue. The planner may propose to split or merge todos (never feedback issues); Ivar's merge of the plan PR is the yes, and the result still waits for his ready.

Todos on needs-clarification, awaiting-decision, blocked-on-content or needs-scoping stay in pending/ until Ivar decides; .planning/dagplanning/ keeps one file per day for the history.

The Websitecheck routine (Monday) is a third source of todos: it reads PostHog and Sentry for the past week, writes .planning/weekrapporten/<year>-W<week>.md and proposes todos on awaiting-decision in a PR (docs/PLAN-website-monitoring.md).

Eefje's retest loop (automated since 2026-05-06)

After a PR merges to staging:

  1. The CI run on the staging push deploys to staging (new SHA, shown in the orange bar on staging.freezedesign.nl)
  2. .github/workflows/feedback-retest-comment.yml β€” triggered on completion of the "CI" workflow_run for staging pushes β€” takes the deployed SHA from that CI run, resolves which PR(s) it contains (scripts/resolve-deployed-prs.sh), parses Feedback: Voorman/freezedesign-feedback#<N> from each PR body, posts one retest comment per issue with the SHA and the "Verify on staging:" steps from each PR (scripts/extract-verify-steps.sh), removes every other status:* label and sets status:retest-pending. A failed PR lookup fails the job loudly instead of silently posting nothing.
  3. Eefje gets a Discord/email notification via the feedback repo's notify-discord workflow
  4. She tests on staging.freezedesign.nl; OK β†’ she closes the issue herself
  5. Not OK β†’ she comments "still broken"; the status flips back via a follow-up PR
  6. Only after her retest is the change promoted to main and released with a vX.Y tag (scripts/release.sh pauses for this; --no-uat is for low-risk changes and still only after the retest)

Agents are not involved in steps 2-6 β€” those run automatically or are human-to-human.

What this costs Ivar daily

  • Morning (5 min, phone): answer the assistant's questions and approve proposals in the intake issues (/ready), and merge the plan PR of the day β€” or not
  • Daytime (Mac): /dagstart, review the wacht-op-ivar PRs and the "Voor Ivar" list, decide on awaiting-decision todos; /enkelspoor starts the next single-track maintenance and process item when there is time
  • Overview: python3 scripts/werkoverzicht.py (or the "Werkbord" page from scripts/werkbord.py) shows per todo and feedback issue who is next
  • Evening retest-WhatsApp β€” automated since 2026-05-06 (retest comment + Discord notification via the feedback repo)

Total: ~5-10 minutes/day for intake, not counting execution.

What this costs Eefje

  • First time: 10 min GitHub onboarding, plus bookmarking the issue form
  • Per report: 2-3 min via the issue form
  • Per retest: varies by item; she closes the issue herself when OK

Anti-patterns to avoid

  1. ❌ Agent creates feedback issues or todos autonomously from Eefje's raw input (PDF, WhatsApp). It will misinterpret ambiguity and create noise. Only Eefje (via the form) or Ivar opens issues.
  2. ❌ Skipping the "needs-clarification" status to keep things moving. Better to block on a 2-minute reply from Eefje than to build the wrong thing.
  3. ❌ Letting raw input bypass the intake layer. If it's not a feedback issue or a todo, it doesn't exist.
  4. ❌ Building before Ivar's yes. An agent never sets status:ready or status: ready itself, and a status:ready that Eefje set does not count. With your gh the label would appear as Voorman's; only do it when Ivar asks in the chat.
  5. ❌ Closing feedback issues yourself, or moving todos to done/ without a check on production. Closing an issue is Eefje's call (after retest on staging); a todo goes to done/ only after the fix is verified on production (Ivar, 2026-10-04).
  6. ❌ Combining multiple issues/todos in one fix unless Ivar explicitly says so. Each report closes independently. The only exception: the planner may propose merging todos in its plan PR; feedback issues are never merged.
  7. ❌ Translating Dutch UI, email or error text to English. The product is Dutch.
  8. ❌ Writing for Ivar or for agents in Eefje's issue (@Voorman, /ready, technical detail). That belongs in the intake issue in this repo.