create-stories

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,docs.density,story_granularity,qa.level,system_overrides`

Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.

Ask with the question tool. Without one, list the options numbered and end your turn
to wait. A skipped or dismissed question is not an answer: ask again in plain text.

# Create Stories

A story is one implementable behaviour: small enough for the size
`story_granularity` sets, self-contained, and traced to a requirement and the
decision that governs it. Run this skill once per epic, in dependency order:
Foundation epics first, then Core, Feature, Presentation.

**Writes:** `production/epics/[epic-slug]/story-NNN-[slug].md`, the epic's
`EPIC.md` Stories table, and its row in `production/epics/index.md`.
**Next:** `/dev-story [story-path]` at `workflow: minimal`; otherwise
`/story-readiness [story-path]`, then `/dev-story`.

Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
asks on major choices, autonomous logs and goes on; `automation_always_ask`
categories always ask).

Checklist (copy it and tick as you go):

```
- [ ] Phase 1: epic found, tier resolved
- [ ] Phase 2: inputs loaded, each ADR's status reported
- [ ] Phase 3-4: stories drafted, typed, Ready or Blocked
- [ ] Phase 5: QA lead review run, or its skip noted
- [ ] Phase 6: story list shown, one ask to write
- [ ] Phase 7: stories, EPIC.md and index.md written (or index absence said)
- [ ] Phase 8: next step asked, closing block printed
```

## Phase 1: Epic and settings

**Tier.** `workflow` for the epic's system: the `system_overrides` row for the epic
slug (its GDD system) if there is one, else the project value.

**`story_granularity`** sets each story's acceptance-criteria load. Group or split
criteria to hit it:

| `story_granularity` | ACs per story | Size |
|---|---|---|
| `coarse` (default, `rigor: minimal`) | 5-10 | a whole feature, multi-day |
| `balanced` (`rigor: standard`) | 2-4 | one task, about one session |
| `fine` | 1 | one criterion; the story name restates it |

**`docs.density`** sets the depth of each story's prose (context, implementation
notes, ADR summary), never the AC count or the AC text: `terse` (default) = bullet
notes, no preamble; `balanced` = a short context paragraph plus notes; `thorough` =
full context, guidance and ADR rationale. The TR-ID, ADR Version and acceptance
criteria are never trimmed.

**Which epic.** The text typed after the skill name, with any `--review <mode>`
pair removed: an epic slug (`combat`) or a path (`production/epics/combat/EPIC.md`).
With nothing typed, the epic the user's request names ("the loot epic") counts as
named.

- **Named, but no `EPIC.md` there:** at `standard` and `full`, stop: "No epic at
  `production/epics/[slug]/EPIC.md`. Run `/create-epics` to create it, or check the
  slug with `ls production/epics/`." Never decompose from a guess. At `minimal`,
  say this tier needs no `/create-epics` epic, take Phase 2's `minimal` branch, and
  name the slug it uses.
- **Blank, at `minimal`:** take Phase 2's `minimal` branch.
- **Blank, at `standard` or `full`:** list `production/epics/*/EPIC.md` with each
  status, then ask: "Which epic would you like to break into stories?" with one
  option per epic. **No epics found:** stop and say "No epics found under
  `production/epics/`. Run `/create-epics layer: foundation` first." Never ask a
  question with no options.

## Phase 2: Load the inputs

### `minimal`: build the epic from the brief

1. **No `design/game-brief.md`:** stop. "There is no brief to build stories from
   yet: run `/brainstorm` first; it writes the one-page brief." When the code root
   already holds the game (10 or more source files), name `/reverse-document design
   [code root]` instead.
2. Read `design/game-brief.md` in full (one page).
3. **The epic.** `<slug>` is the brief's working title, slugified (`mvp` if it has
   none), or the epic the user named.
   - `production/epics/<slug>/EPIC.md` exists: it is the epic. Use its scope, still
     traced to the brief, and never rewrite it.
   - It does not: draft one, written in Phase 7 only after the Phase 6 ask names
     it. Goal = the brief's one-sentence pitch; scope = its MVP feature list;
     order = its **Build order**. Keep it terse.
   - Stories already in the folder (a return visit): never rewrite an existing
     `story-*.md`. Add stories only for brief items they do not cover, or new ones
     the user names, and number on from the highest existing `story-NNN`.
4. **One story per MVP feature, in Build order**, each traced to the brief. No
   story is blocked on ADR grounds: this tier has none.

Read no GDD, control manifest, TR registry or ADR at `minimal`. Go to Phase 3.

### `standard` and `full`: the epic and what governs it

1. **The epic:** `production/epics/[epic-slug]/EPIC.md` in full (its layer, GDD,
   governing ADRs, and the GDD Requirements table with TR-IDs).
2. **The GDD:** its sections by heading, never the whole file:
   `bash .claude/scripts/md-section.sh extract design/gdd/[file].md "Acceptance Criteria"`,
   and the same for `Formulas`, `Edge Cases` and `Detailed Design` (exit 3: try
   `Detailed Rules`, the design standard's name for the same section); at `full`
   the other required sections too (`list` shows the headings).
3. **The control manifest:** the epic's layer only, and the version:
   `bash .claude/scripts/md-section.sh extract docs/architecture/control-manifest.md "[Layer] Layer Rules"`,
   plus its `Manifest Version` line.
4. **The TR registry:** this system's entries only: in
   `docs/architecture/tr-registry.yaml`, the lines matching `system: <slug>\s*$`,
   with each entry's `id` above and its text below. The anchor keeps `combat` from
   matching `combat-ai`; `\s*` takes a Windows line ending.
5. **The ADRs**, every one the epic names (governing, or in its requirements table,
   Proposed ones included), in one call:
   ```
   bash .claude/scripts/adr-status.sh ADR-0001 ADR-0003 ...
   ```
   Each row gives the status, layer, `version` (the story's ADR Version stamp),
   `depends_on`, and missing sections. Then read only `Summary`, `Decision` (its
   Implementation Guidelines inside) and `Engine Compatibility` of each, with
   `md-section.sh extract`. Engine Notes is a story field taken from Engine
   Compatibility, not an ADR section. An ADR with none of these sections predates
   the template: read it once, and flag it for `/architecture-decision retrofit
   [file]`.

**A named ADR with no file** (`NOT_FOUND`):

- `full`: stop before decomposing any story.
- `standard`: stop only when it is critical (Foundation layer); otherwise warn, go
  on, and write the stories it governs as `Blocked` until it exists.
- On stopping: "Epic references [ADR-NNNN: title] but no file for it was found in
  `docs/architecture/`. Check the epic's Governing ADRs list, or run
  `/architecture-decision` to create it. Cannot create stories until the
  referenced ADR files exist."

**Report before drafting**, with the real state, every ADR on its own with its
status:

```
Loaded: epic [name] · GDD [file] · manifest v[date], [layer] rules
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0003 Accepted · ADR-0004 Proposed · [ADR-NNNN missing]
```

Never say "all present" when one is missing, or name a manifest version when there
is none.

## Phase 3: Type each story

| Type | When its criteria reference |
|---|---|
| **Logic** | formulas, thresholds, state transitions, AI decisions, calculations |
| **Integration** | two or more systems, signals across boundaries, save/load round-trips |
| **Visual/Feel** | animation, VFX, "feels responsive", timing, screen shake, audio sync |
| **UI** | menus, HUD, buttons, screens, dialogue boxes, tooltips |
| **Config/Data** | balance values and data files only, no new logic |

A mixed story takes the type with the highest implementation risk. The type sets
the evidence `/story-done` needs.

## Phase 4: Draft the stories

Group the requirements that need the same core implementation into one story, at
the `story_granularity` load. Order: foundation behaviour first, edge cases later,
UI last. For each story:

- **Requirement:** the TR-ID from the registry, matched through the epic's GDD
  Requirements table. Only when no entry matches, write `TR-[system]-???` and say
  so.
- **ADR:** the one that governs how to build it (the requirements table names it).
  - `Accepted`: embed it.
  - `Proposed`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is Proposed — accept it
    with `/architecture-decision accept ADR-NNNN` once decided".
  - `Deprecated` or `Superseded`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is
    [status] — point the story at [successor] (edit its ADR field;
    `/create-stories` never rewrites an existing story) before implementing".
  - An `Accepted` ADR whose `depends_on` names an ADR that is not Accepted: Blocked
    the same way, naming that ADR.
  - Several apply: list them all, the most direct first.
  - None applies: `ADR: N/A — [reason]`, e.g. "pure data configuration". Never
    blank: blank means unchecked.
- **ADR Version:** the story's **ADR Version** is the ADR's `## Last Verified`
  date, else its `## Date`, else `unversioned` (the `version` column). `/dev-story`
  trusts the story's ADR summary while this still matches the ADR.
- **Engine risk:** from the ADR's Engine Compatibility (its knowledge risk).
- **Estimate:** propose a t-shirt size from the criteria and the files the story
  touches: `S` (a few hours), `M` (about a day) or `L` (several days). It is a
  proposal: Phase 6 shows it and the user can change it. `/story-readiness` fails
  a story whose Estimate is still the template's bracket, so never leave it.

## Phase 5: QA lead review

Read the `review_gate` line above. `skill-gates=skip` (solo or lean): no review;
note "QL-STORY-READY skipped — [Solo | Lean] mode" in the Phase 6 list and the
closing block. `skill-gates=run`: read `references/qa-lead-gate.md` and
`.claude/docs/director-gates.md`, and run it now, before the Phase 6 ask. On a skip,
do not load it.

## Phase 6: Show the stories, ask once

```
## Stories for Epic: [name]
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0004 Proposed   (every ADR, from Phase 2)

Story 001: [title] — Logic — ADR-0001 — Ready — Estimate M
  Covers: TR-[system]-001 ([one-line requirement])
  Test required: tests/unit/[system]/[slug]_test.[ext]

Story 002: [title] — Integration — ADR-0004 — BLOCKED (ADR-0004 is Proposed) — Estimate L
  Covers: TR-[system]-002, TR-[system]-003
  Test required: tests/integration/[system]/[slug]_test.[ext]

Story 003: [title] — Visual/Feel — ADR-0001 — Ready — Estimate S
  Covers: TR-[system]-004
  Evidence required: retained screenshot + sign-off in production/qa/evidence/[slug]-evidence.md

[N stories: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data; N Blocked]
QL-STORY-READY: [skipped — Solo mode | its verdicts]
```

At `minimal`, each line traces to `Brief MVP feature N`, there is no ADRs line, and
there is one story per MVP feature: no extra stories for brief items outside the
MVP list. Then
ask: "May I write these [N] stories to `production/epics/[epic-slug]/`, and
[create | update] `production/epics/[epic-slug]/EPIC.md` and update
`production/epics/index.md`?" Options: Yes, write all [N] / Not yet, I want to
adjust first; an adjustment can change any estimate. Name every file Phase 7 touches: *create* `EPIC.md` only when it
does not exist, and leave `index.md` out when it does not exist. Write nothing
before the yes.

## Phase 7: Write

### The story files

**Each story** is `production/epics/[epic-slug]/story-[NNN]-[slug].md`, laid out
as `.claude/docs/templates/story.md`. Never reuse a story number. Write each file
as a file, never through a shell command: a shell write skips the project's write
checks.

At `minimal` there is no GDD, ADR, TR registry or manifest. Fill these fields
exactly:

| Field | Value at `minimal` |
|---|---|
| GDD | `design/game-brief.md` |
| Requirement | `Brief MVP feature N`, never a TR-ID |
| ADR Governing Implementation, ADR Decision Summary, ADR Version | `N/A (minimal — no ADRs)` |
| Manifest Version, Control Manifest Rules | `N/A (minimal — no control manifest)` |
| Engine | `engine.name` + `engine.version` |
| Risk | the level `docs/engine-reference/<engine>/VERSION.md` gives the pinned version (its timeline row, or its overall rating). No file or no level: `NOT ASSESSED (no VERSION.md risk rating)`, never a guess. `/dev-story` reads NOT ASSESSED as HIGH |
| Engine Notes | `none (no ADR engine-compatibility analysis at minimal)` |
| Acceptance Criteria | from the brief's **Player goal & fail state** and the MVP feature, made concrete and testable; never invented from a bare bullet |

At every tier:
- **QA Test Cases:** when the review was skipped, write
  `*N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*`.
  Never improvise test cases.
- **Test Evidence:** `qa.level` governs it. At `qa.level: minimal` tests are
  waived (advisory), but a Visual/Feel or UI story's retained screenshot is not.
- **Estimate:** the size from Phase 6, with any change the user made.
- **Dependencies:** name each story this one needs by its path.
- **Files:** the code and test files the story is planned to create or change,
  under the code root and test root. `/dev-story` replaces them with the real list.

### `EPIC.md`

At `minimal` with none yet, write the Phase 2 draft with the table
below. Otherwise replace its "Stories: Not yet created" line with the table, or on
a return visit append one row per new story and leave the rest of the file as it
is:

```markdown
## Stories

| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-0001 |
| 002 | [title] | Integration | Blocked | ADR-0004 |
```

### `production/epics/index.md`

Set the epic's `Stories` cell to `[N] stories`,
the epic's total after this run. When the file does not exist, say so:
`Epics index not updated: production/epics/index.md absent`.

## Phase 8: Close

If other epics in `production/epics/` have no stories, list them. Then ask:
"[N] stories written to `production/epics/[epic-slug]/`. What next?" Options, those
that apply:

- Start implementing: `/dev-story [first-story-path]` at `minimal`,
  `/story-readiness [first-story-path]` otherwise (recommended)
- Create stories for [next epic]: `/create-stories [slug]` (only when an epic has
  none)
- Plan the sprint: `/sprint-plan new` (only when every epic has stories; never at
  `minimal`, where the brief's build order is the plan)
- Stop here for this session

Never start implementation or write code: this skill stops at the story files.
Acceptance criteria come from the GDD (the brief at `minimal`), implementation
notes from the ADRs, rules from the manifest; none are invented.

**The run's last reply ends with this block**, after the question above is
answered (repeat it if you showed it earlier):

```
Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/ ([N] Ready, [N] Blocked)
Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdicts]
Index: [production/epics/index.md updated | Epics index not updated: production/epics/index.md absent]
Next step: [/dev-story [first-story-path] | /story-readiness [first-story-path]]
```

When the user declines the write: `Verdict: BLOCKED — user declined. No story
files written.`

Shown under the source repo’s MIT license. Read the full folder on GitHub.