Stories: from scope to tickets for client builds

One pipeline so every person and agent writes, works and closes client tickets the same way. It works for Linear and GitHub Issues; the content is identical, only the call that creates the ticket differs.

Where the files live

Each step writes one file in the project's planning folder. Use the folder the team already keeps for this client (ask once if none is obvious); otherwise .context/stories/<client>/ in the build repo. Name it once in the stories doc and reuse it.

The pipeline

Run the steps in order. Skipping a step is what makes tickets thin, not the template.

Stop for client approval

After writing user-stories.md, stop. Report the file path, the story count, and the open questions, and say that the client approves the doc before any ticket exists. End the turn there. Do not write the implementation review or create a ticket in the same run, even when the user says the client will approve. Steps 3 onward start in a new invocation that names the approval: who approved, when, and any changes.

When the design or the scope changes after approval, revalidate the affected stories and flag each change inline with its date ("Updated 18 May per the revised design: ..."). Never silently rewrite an approved story.

Writing stories and criteria

• Granularity. One story per user-visible module (a section, a page, a component the visitor sees) or per merchant capability ("the store owner edits the goal without code").
• Criteria are for whoever signs off, client or QA, not the implementer. Each one is checkable in one look or one action: say the number, the copy, the breakpoint.
• Cover mobile, every state (empty, sold out, ended, error), every setting the merchant edits, and explicit negatives ("No carousel", "No tracking").
• Implementation detail stays out. File names, events, intervals and APIs go in Implementation notes, where the developer can challenge them.
• Four to ten criteria. More means the story is two stories.

Creating tickets (step 4)

1. Read references/ticket.md and fill one ticket per approved story: the story and criteria verbatim, the review's notes in Implementation notes.
2. The ticket closes on its own criteria. A parent that only says "done when the sub-issues are done" is not allowed.
3. Sub-issues only when different people build the pieces or a piece is shared by two or more tickets. A shared piece is built once, in the ticket that needs it first; that ticket says it is shared, and each consumer names it and reuses it.
4. Design references on every front-end ticket: the desktop and the mobile frame, each described in words (frame name, where the block sits, the text on it). Never a bare node ID.
5. Shared rules live once in the kickoff: the standard Verify commands, the screenshot QA protocol, branch and push rules, the data contract, the decisions table. A ticket carries only what is specific to it.
6. Write every ticket to tickets.md first, run the /dr-review Ticket Review on it, and fix every flag until the verdict is READY. Show the count, then create them in the project's tracker:
   • Linear: spawn the linear agent with event tickets, the path to tickets.md, and the repo. It creates the stories, their sub-issues and blocked-by relations in the mapped team and project.
   • GitHub Issues: gh issue create --title <title> --body-file <file> per ticket, one body file each; link sub-issues from the parent body.
7. The tracker is now the source of truth. The local docs become dated snapshots. Never re-run a generator over the tracker; change tickets in the tracker.

Kickoff, QA and closing (steps 5 to 7)

• Write the kickoff after the repo exists, from references/kickoff.md; its most valuable section points at real files. Post it where the team keeps project docs and link it from every ticket.
• Write qa-checklist.md from references/qa-checklist.md. Before launch, the session that runs /stories walks it: spawn the tester agent for the browser checks and screenshots, mark each item seen or failed, and leave anything nobody saw open. The launch waits on open items.
• The closing comment is posted per ticket when its work is ready for review, from references/closing-comment.md. /build drafts it at the end of a ticket's build.

Anti-patterns

/dr-review flags these on tickets. Do not write them:

• A story as a container: the parent has no criteria of its own.
• Tickets split by technical layer before the story is agreed with the client.
• Tickets written in one pass from the contract and the design, with no implementation review and no client approval in between.
• Implementation detail written as acceptance criteria.
• The same Verify or QA boilerplate pasted into every ticket.
• Bare design node IDs with no description.
• Status set to done from a reasoned check instead of a seen one.

Evidence

Mirae (darkroomengineering/shopify_horizon #33 to #44) shipped cleanly because of the steps before the tickets: scope answers, a client-approved story doc, an implementation review. The Sweet Death first pass (Nov 2026), 14 stories and 55 sub-issues written in one day from a proposal and wireframes, came out thin in exactly the ways listed above.