/create-stories

name: create-stories
description: "Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic."
argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
model: sonnet
agent: lead-programmer

Create Stories

A story is a single implementable behaviour — small enough to complete in one focused session, self-contained, and fully traceable to a GDD requirement and an ADR decision. Stories are what developers pick up. Epics are what architects define.

**Run this skill per epic**, not per layer. Run it for Foundation epics first, then Core, and so on — matching the dependency order.

**Output:** `production/epics/[epic-slug]/story-NNN-[slug].md` files

**Previous step:** `/create-epics [system]` **Next step after stories exist:** `/story-readiness [story-path]` then `/dev-story [story-path]`

---

1. Parse Argument

Extract `--review [full|lean|solo]` if present and store as the review mode override for this run. If not provided, read `production/review-mode.txt` (default `lean` if missing). This resolved mode applies to all gate spawns in this skill — apply the check pattern from `.claude/docs/director-gates.md` before every gate invocation.

• `/create-stories [epic-slug]` — e.g. `/create-stories combat`
• `/create-stories production/epics/combat/EPIC.md` — full path also accepted
• No argument — ask: "Which epic would you like to break into stories?"

Glob `production/epics/*/EPIC.md` and list available epics with their status.

---

2. Load Everything for This Epic

Read in full:

• `production/epics/[epic-slug]/EPIC.md` — epic overview, governing ADRs, GDD requirements table
• The epic's GDD (`design/gdd/[filename].md`) — read all 8 sections, especially Acceptance Criteria, Formulas, and Edge Cases
• All governing ADRs listed in the epic — read the Decision, Implementation Guidelines, Engine Compatibility, and Engine Notes sections
• `docs/architecture/control-manifest.md` — extract rules for this epic's layer; note the Manifest Version date from the header
• `docs/architecture/tr-registry.yaml` — load all TR-IDs for this system

**ADR existence validation**: After reading the governing ADRs list from the epic, confirm each ADR file exists on disk. If any ADR file cannot be found, **stop immediately** before decomposing any story:

> "Epic references [ADR-NNNN: title] but `docs/architecture/[adr-file].md` was not found. > Check the filename in the epic's Governing ADRs list, or run `/architecture-decision` > to create it. Cannot create stories until all referenced ADR files are present."

Do not proceed to Step 3 until all referenced ADR files are confirmed present.

Report: "Loaded epic [name], GDD [filename], [N] governing ADRs (all confirmed present), control manifest v[date]."

---

3. Classify Stories by Type

**Story Type Classification** — assign each story a type based on its acceptance criteria:

| Story Type | Assign when criteria reference... | |---|---| | **Logic** | Formulas, numerical thresholds, state transitions, AI decisions, calculations | | **Integration** | Two or more systems interacting, signals crossing boundaries, save/load round-trips | | **Visual/Feel** | Animation behaviour, VFX, "feels responsive", timing, screen shake, audio sync | | **UI** | Menus, HUD elements, buttons, screens, dialogue boxes, tooltips | | **Config/Data** | Balance tuning values, data file changes only — no new code logic |

Mixed stories: assign the type that carries the highest implementation risk. The type determines what test evidence is required before `/story-done` can close the story.

---

4. Decompose the GDD into Stories

For each GDD acceptance criterion:

1. Group related criteria that require the same core implementation 2. Each group = one story 3. Order stories: foundational behaviour first, edge cases last, UI last

**Story sizing rule:** one story = one focused session (~2-4 hours). If a group of criteria would take longer, split into two stories.

For each story, determine:

• **GDD requirement**: which acceptance criterion(ia) does this satisfy?
• **TR-ID**: look up in `tr-registry.yaml`. Use the stable ID. If no match, use `TR-[system]-???` and warn.
• **Governing ADR**: which ADR governs how to implement this?
• `Status: Accepted` → embed normally
• `Status: Proposed` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is Proposed — run `/architecture-decision` to advance it"
• **Multiple ADRs apply**: List all governing ADRs in the story's `Governing ADRs:` field. Designate the one most directly controlling the implementation pattern as primary (first in the list). Others are listed as secondary references.
• **No ADR applies at all**: Write `ADR: N/A — [brief reason, e.g. "pure data configuration, no architectural pattern required"]` in the story's ADR field. Do NOT leave the field blank — a blank ADR field means "not checked", not "not applicable".
• **Story Type**: from Step 3 classification
• **Engine risk**: from the ADR's Knowledge Risk field

---

4b. QA Lead Story Readiness Gate

**Review mode check** — apply before spawning QL-STORY-READY:

• `solo` → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to Step 5 (present stories for review).
• `lean` → skip (not a PHASE-GATE). Note: "QL-STORY-READY skipped — Lean mode." Proceed to Step 5 (present stories for review).
• `full` → spawn as normal.

After decomposing all stories (Step 4 complete) but before presenting them for write approval, spawn `qa-lead` via Task using gate **QL-STORY-READY** (`.claude/docs/director-gates.md`).

Pass: the full story list with acceptance criteria, story types, and TR-IDs; the epic's GDD acceptance criteria for reference.

Present the