/story-done

name: story-done
description: "End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint."
argument-hint: "[story-file-path] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion, Task
model: sonnet

Story Done

This skill closes the loop between design and implementation. Run it at the end of implementing any story. It ensures every acceptance criterion is verified before the story is marked done, GDD and ADR deviations are explicitly documented rather than silently introduced, code review is prompted rather than forgotten, and the story file reflects actual completion status.

**Output:** Updated story file (Status: Complete) + surfaced next story.

---

Phase 1: Find the Story

Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean`

See `.claude/docs/director-gates.md` for the full check pattern.

**If a file path is provided** (e.g., `/story-done production/epics/core/story-damage-calculator.md`): read that file directly.

**If no argument is provided:**

1. Check `production/session-state/active.md` for the currently active story. 2. If not found there, read the most recent file in `production/sprints/` and look for stories marked IN PROGRESS. 3. If multiple in-progress stories are found, use `AskUserQuestion`:

• "Which story are we completing?"
• Options: list the in-progress story file names.

4. If no story can be found, ask the user to provide the path.

---

Phase 2: Read the Story

Read the full story file. Extract and hold in context:

• **Story name and ID**
• **GDD Requirement TR-ID(s)** referenced (e.g., `TR-combat-001`)
• **Manifest Version** embedded in the story header (e.g., `2026-03-10`)
• **ADR reference(s)** referenced
• **Acceptance Criteria** — the complete list (every checkbox item)
• **Implementation files** — files listed under "files to create/modify"
• **Story Type** — the `Type:` field from the story header (Logic / Integration / Visual/Feel / UI / Config/Data)
• **Engine notes** — any engine-specific constraints noted
• **Definition of Done** — if present, the story-level DoD
• **Estimated vs actual scope** — if an estimate was noted

Also read:

• `docs/architecture/tr-registry.yaml` — look up each TR-ID in the story.

Read the *current* `requirement` text from the registry entry. This is the source of truth for what the GDD required — do not use any requirement text that may be quoted inline in the story (it may be stale).

• The referenced GDD section — just the acceptance criteria and key rules, not

the full document. Use this to cross-check the registry text is still accurate.

• The referenced ADR(s) — just the Decision and Consequences sections
• `docs/architecture/control-manifest.md` header — extract the current

`Manifest Version:` date (used in Phase 4 staleness check)

---

Phase 3: Verify Acceptance Criteria

For each acceptance criterion in the story, attempt verification using one of three methods:

Automatic verification (run without asking)

• **File existence check**: `Glob` for files the story said would be created.
• **Test pass check**: if a test file path is mentioned, run it via `Bash`.
• **No hardcoded values check**: `Grep` for numeric literals in gameplay code

paths that should be in config files.

• **No hardcoded strings check**: `Grep` for player-facing strings in `src/`

that should be in localization files.

• **Dependency check**: if a criterion says "depends on X", check that X exists.

Manual verification with confirmation (use `AskUserQuestion`)

• Criteria about subjective qualities ("feels responsive", "animations play correctly")
• Criteria about gameplay behaviour ("player takes damage when...", "enemy responds to...")
• Performance criteria ("completes within Xms") — ask if profiled or accept as assumed

Batch up to 4 manual verification questions into a single `AskUserQuestion` call:

question: "Does [criterion]?"
options: "Yes — passes", "No — fails", "Not tested yet"

Unverifiable (flag without blocking)

• Criteria that require a full game build to test (end-to-end gameplay scenarios)
• Mark as: `DEFERRED — requires playtest session`

Test-Criterion Traceability

After completing the pass/fail/deferred check above, map each acceptance criterion to the test that covers it:

For each acceptance criterion in the story:

1. Ask: is there a test — unit, integration, or confirmed manual playtest — that directly verifies this criterion?

• **Unit test**: check `tests/unit/` for a test file or function name that

matches the criterion's subject (use `Glob` and `Grep`)

• **Integration test**: check `tests/integration/` similarly
• **Manual confirmation**: if the criterion was verified via `AskUserQuestion`

above with a "Yes — passes" answer, count that as a manual test

2. Produce a traceability table:

| Criterion | Test | Status |
|-----------|------|--------|
| AC-1: [criterion text] | tests/unit/test_foo.gd::test_bar | COVERED |
| AC-2: [criterion text] | Manual playtest confirmation | COVERED |
| AC-3: [criterion text] | — | UNTESTED |

3. Apply these escalation rules:

• If **>50% of criteria are UNTESTED**: escalate to **BLOCKING** — test

coverage is insufficient to confirm the story is actually done. The verdict in Phase 6 cannot be COMPLETE until coverage improves.

• If **some (≤50%) criteria are UNTESTED**: remain ADVISORY — does not block

completion, but must appear in Completion Notes.

• If **all criteria are COVERED**: no action needed beyond including the

table in the report.

4. For any ADVI