Backlog — epics, stories, waves

Inputs: docs/context/*, docs/prd.md, and the code if it exists. Output: backlog/epics.md and backlog/stories/<ID>-<slug>.md in the format of backlog/README.md. Status is never written: a story is done when a commit on main carries the trailer Story: <ID>.

1. Epics

3–7 epics that map to the PRD's in-scope capabilities, each with: id (short uppercase word, e.g. AUTH), goal in one sentence, the PRD line it serves, and what is explicitly outside it. Anything in the PRD's "out" list never becomes a story.

2. Stories

• Vertical slices: each story delivers something a user or operator can observe end to end (API + UI + test), sized to one focused session. Split anything bigger; merge anything that can't be observed alone.
• Id EPIC-NNN, never reused. File name <ID>-<slug>.md.
• Front matter (+++ TOML): id, epic, title, wave, depends_on, touches (the paths it will change — directories are fine), dimensions (what it can break, from ${CLAUDE_PLUGIN_ROOT}/references/dimensions.md: a screen implies at least ux, ui, i18n, a11y; an endpoint implies api, contract, auth), and invariants (the INV-nnn from docs/context/domain.md the story must keep; listing any means declaring integrity, and touching a critical area from .keelokit/critical.toml means both). No status. Optional origin when the story comes from somewhere other than the first plan: "bugbash:<date> <finding id>" or "feature:<date>" (a later feature intake).
• Body sections, in order:
  1. Context — why, with references to docs/context / PRD sections, and a Does NOT do list.
  2. User story — As a <user>, I want <capability>, so that <outcome>.
  3. Acceptance criteria — Gherkin, one Scenario: [S1] … per behaviour (ids are how tests trace back: AUTH-003.S1). Cover, per declared dimension, the uncomfortable cases: empty, error, loading, no permission, another role, expired session, other locale, 320 px, twice in a row, two at once. The invariants go in the front matter, not as scenarios: each one gets the test its class calls for (${CLAUDE_PLUGIN_ROOT}/references/invariants.md).
  4. Testable units — table: unit · test type (unit / integration / e2e) · file.
  5. Definition of done — pnpm verify green, every scenario covered by a test titled with its id, Story: <ID> trailer on the completing commit, addendum if the result differs.
• A story that needs an unknown fact gets the [GAP-nnn] reference and depends on answering it (record the gap in docs/context/gaps.md); never fill the hole with a guess.

3. Consolidate (always, and when re-planning)

• Merge duplicates and overlapping stories; keep the lower id.
• Stories already done (Story: trailer on main) are never edited, renumbered or deleted; changes to done work become new stories.
• Every PRD in-scope line is covered by at least one story; every story traces to one.

4. Prioritise and wave

1. Order: what unblocks the most first (foundations, then the core user journey), then PRD priority, then risk (unknowns early).
2. Waves: a story goes in the earliest wave where all depends_on are in earlier waves and its touches don't overlap any other story in the same wave (same file, or one path inside another) and it shares no critical area with another story of the wave. Overlap → next wave; python3 .keelokit/bin/doctor.py fails on both. This is what lets several agents build in parallel safely, and what keeps critical work (money, notices, limits, orchestrators) one story at a time.
3. Critical areas: when the plan creates code where a bug moves money, repeats a side effect, breaks a limit or leaks data, propose an area for .keelokit/critical.toml (name, why, paths) to the user, and point its stories at it. Shared orchestrators that many stories call are good candidates: serialising them is cheap, a collision in them is not.
4. Write backlog/epics.md: the epics table, then one table per wave (Story · Title · Depends on · Touches), then a short "collisions resolved" note for stories moved to a later wave because of overlap.

5. Check

Run python3 .keelokit/bin/doctor.py and fix every backlog error (ids, file names, unknown dependencies, stray status). Refresh the dashboard (/keelokit:project-dashboard): it shows the stories by wave and by epic. Then show the user in the chat: epics, stories per wave, the first ready stories, and any story blocked by a gap — and ask them to approve the order. Talking to the user in Spanish, waves are olas de desarrollo; say once what one is (stories that don't touch the same files, so they can be built at the same time).