clnnn To User Stories
Synthesise what this conversation already holds into implementation-ready stories, each written for a fresh agent: an implementer with the code in front of them but none of this conversation. No interview — the conversation is the material. One checkpoint: the seams.
Ground rules
- Use the project's domain glossary vocabulary throughout the user story, and respect any ADRs in the area you're touching.
- Tracker verbs this skill names in bold — publish, link A blocked by B, apply a label — are defined by the project's issue tracker doc.
- The
codebase-designskill is the seam vocabulary; its terms (module, interface, seam, adapter, depth) are the words §5 and §6 use.
Step 1/6 — Ground
The feature is whatever the invocation named, else the one this conversation is about.
Ground in one dispatch: an exploring subagent for the current state of the code the feature touches — what already runs, what the change has to reach — sent in the same message as your own reads of the design references the invocation or the conversation names, the glossary (its exact words carry the Step 6 checks, and a subagent's summary loses them), the ADRs covering the area, the issue tracker doc, and the codebase-design skill. Everything the run needs arrives before its one gate, and the tracker verbs are in context long before Step 6 writes.
The glossary's vocabulary carries through every story. Where a story's work contradicts an ADR, surface it — "contradicts ADR-0003, worth reopening because…" — rather than silently overriding.
Advance when the touched code, the design references, the glossary terms, the ADRs covering the area, the tracker verbs, and the seam vocabulary are all in context.
Step 2/6 — Design
Every story that puts something on screen carries its design decisions. Extract them here, from the reference — the Figma frames, Claude Design canvas, /prototype output, or screenshots this conversation names.
No UI surface — the feature changes nothing a user sees. Say so, and the design section of each story stays empty.
Reference in hand — read it: images and local canvas or prototype files directly, a published Claude Design canvas by its URL, Figma frames through a connected Figma tool, else ask for them exported as images. Then record, per surface:
- Reference — the link plus the frame or artboard name. Cite it; a screen transcribed into prose goes stale the moment the designer moves a pixel.
- States — the states the reference designs: empty, loading, populated, long-content, error, and the disabled or in-flight variant of every action. A state the reference leaves out is named as undesigned, and stays undesigned — inventing one here buries a design decision in a ticket.
- Components — the components already in the codebase this surface reuses, and the ones that have to be new.
- Deviations — where the reference departs from the design system in the repo, and which of the two wins.
- Beyond the frame — what a static reference cannot show: responsive breakpoints, focus and keyboard order, motion, and the real copy behind its placeholder text.
No reference — the design question is open. Name it and recommend /prototype's UI branch or a Claude Design canvas. The run continues: the first slice ships the plainest surface that delivers the value, and every polish decision waiting on a reference is split off at Step 5, Pattern 5.
Variations the reference does show — a richer input, a second breakpoint, an animated transition — go to Step 5 as Pattern 5 and 7 candidates rather than into the first slice.
Advance when every state the feature's flows pass through is either designed in the reference or named undesigned, and every surface carries its cited reference.
Step 3/6 — Seams
Sketch the seams at which the feature gets tested, in the codebase-design skill's words. A designed surface is seamed through the components Step 2 named, existing ones first.
- Existing over new. A seam already in the codebase costs nothing to test through.
- Highest possible. The seam that observes the most behaviour per unit of interface a test has to learn. A new seam is proposed at the highest point it can sit.
- Fewest. One seam across the whole feature is the target; each extra one is a cost to justify.
Present each seam — where it sits, existing or new, what a test sees through it — and ask the user whether they match expectations. This is the skill's one gate: hold until the answer comes, and apply their corrections before splitting.
Advance when the user confirms the seams.
Step 4/6 — INVEST pre-check
Run the material through this before any split:
| Check | Question | On failure |
|---|---|---|
| Independent | Prioritizable without hard technical dependencies? | Flag the dependency; it becomes a blocked by edge at publish |
| Negotiable | Room for the team to discover implementation, not a prescriptive spec? | Reframe before splitting |
| Valuable | Observable user value? | Stop. Don't split a technical task — combine it with related work into a meaningful increment |
| Estimable | Team can size it roughly? | Run a spike first (Pattern 9) |
| Testable | Concrete pass/fail acceptance criteria? | Refine criteria before splitting |
| Small | Completable in ≈1–5 days? | Too big is the normal case — Step 5 is what fixes it |
Advance when every row passes or carries its stated remedy.
Step 5/6 — Split
Every story is a vertical slice: it cuts through all layers and delivers observable user value. Walk the patterns in order and take the first that fits — a clean "no, next pattern" is the correct move.
- Workflow Steps — multi-step workflow? Split into thin end-to-end slices, never step-by-step. Story 1 = the full workflow via the simplest path (upload → live, no reviews); later stories add intermediate steps (editorial review, legal approval). Each story delivers the whole workflow at increasing sophistication.
- Operations (CRUD) — "manage / handle / maintain" signals bundled operations. One story per operation: create, view, edit, delete.
- Business Rule Variations — identical functionality under different rules (tiers, regions, conditions)? One story per rule.
- Data Variations — different data types, formats, or structures? One story per variation, simplest first, added just-in-time.
- Data Entry Methods — fancy UI (date picker, autocomplete, drag-and-drop) riding on core functionality? Story 1 = plain input, later stories = UI polish.
- Major Effort — first implementation carries the weight, additions are trivial (the first card network builds the whole payment pipeline)? Story 1 = implement one, Story 2 = add the remaining variants.
- Simple/Complex — ask "what's the simplest version that still delivers value?" That's Story 1; each stripped-away complexity becomes its own story.
- Defer Performance — split "make it work" from "make it fast." Story 1 = functional, Story 2 = meet the performance/scale target.
- Break Out a Spike — none of 1–8 fit ⇒ uncertainty is the blocker. Time-box a short investigation answering one named question (feasibility, approach, what the API returns). A spike produces learning, not shippable code, so it cannot be split further: write it as a story whose §3 is the question answered, publish it as the only ticket of this run, and stop — the next run restarts at Pattern 1 with the answer in hand.
Meta-pattern — runs inside whichever pattern fits:
- Identify the core complexity — what makes this epic hard?
- List all variations.
- Reduce to one complete slice — the simplest variation that still delivers end-to-end value.
- Make every other variation its own story.
Split evaluation. A split earns its keep by at least one of:
- It reveals low-value work — the 80/20 exposed: a slice to deprioritize or kill ("flexible dates is rarely used → defer"). Report it as a finding and recommend dropping it.
- It yields roughly equal-sized stories — equal slices give the product owner reordering freedom.
Neither satisfied → try the next pattern. Any resulting story still failing Small → restart it at Pattern 1 and split again.
Advance when every slice is vertical, INVEST-passing including Small, and its producing pattern is named.
Step 6/6 — Write & publish
Read template.md and write each slice with it. The pass that follows runs in flight rather than as a phase after the writing: a story's agent goes out the moment that story is written, while the remaining slices are still being written.
Fresh agent — one per story, dispatched as its story is finished, with that story body and the repo: no conversation, no other story. A context holding exactly one story is the whole point of this agent, so it is the one charge that stays per-story. Its charge: plan the implementation, reading only — every question you have to ask to plan it is a gap.
Set auditors — two agents over every story body at once, both dispatched in one message as the last slice lands. Reading the stories as a set is what catches the cross-story failures a per-story critic is blind to: one domain term used two ways across two stories, one story's §2 Out naming work no other story owns. Each is briefed to break the stories; a report of "looks fine" is a failed dispatch.
| Agent | Context it gets | Charge |
|---|---|---|
| Slice auditor | Every story body | Per story, prove this slice is not vertical: name a layer it fails to cut, or user-observable value it fails to deliver. Across the set, name any two stories that overlap and any slice no story covers. |
| Glossary cop | Every story body, the glossary, the ADRs covering the area | Name every term that is not a glossary term, every glossary term used in other words, every term used one way in one story and another way in another, and every line contradicting an ADR. |
Checks — run these over every story while the set auditors work:
| # | Check |
|---|---|
| 1 | §2 Out is non-empty and names real neighbouring work: the next slice's tasks, the adjacent workflow step, variations split off during the split |
| 2 | Every domain term is a glossary term, used in the glossary's words and never redefined — an _Avoid_ synonym never appears |
| 3 | Every §3 scenario has exactly one When and one Then |
| 4 | §3 covers the happy path, every edge case, every failure mode |
| 5 | Every Then is observable — a state, message, or number someone can check ("better/faster/improved" fails) |
| 6 | §4 cites each surface's reference by link and frame name, and every line under it is a decision the reference itself cannot show — §4 is empty only where the story changes nothing a user sees |
| 7 | Every state a §3 scenario asserts on is designed in §4 or named there as undesigned |
| 8 | §5 and §6 name modules, interfaces and seams — no file paths, and no code beyond a decision-encoding snippet; both go stale within the week |
| 9 | §6's seams are the seams confirmed at Step 3 |
Rulings — one round. Every finding is a check failure: rewrite, then re-verify the sections the rewrite touched, and re-dispatch a fresh agent for the stories whose §3, §4, §5, or §6 changed. The fresh agent is the one that tests this skill's premise, so its questions outrank the checks table: a story it cannot implement is not ready, all-green or not — and that alone earns a second round.
Publish — create every ticket in one batch, title = story title, body = the six sections. Creates are independent of each other; dependency order lives in the edges, not in the order of creation. Record each returned number, then link A blocked by B for every dependency the INVEST pre-check flagged, and apply a label named for the feature to every ticket in the run. Report each story title with its ticket ref and blockers, plus any slice the split flagged as killable.
Done when every story has survived the pass, holds a ticket ref, and every flagged dependency has an edge.