/story-done

name: story-done
description: "Closes a finished story: verifies each acceptance criterion, checks for design or ADR deviations and updates its status. Use when the user says a story is done, finished or ready to close."
argument-hint: "[story-file-path] [--review full|lean|solo]"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-done/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/story-facts.sh *), Bash(bash .claude/scripts/story-status.sh*), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh *), Bash(bash .claude/scripts/review-receipts.sh check *), Bash(bash .claude/scripts/session-state.sh *), Bash(git status --porcelain*), Bash(git add -- *), Bash(git commit -m *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,qa.level,gate_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.

Story Done

Closes a finished story. Every acceptance criterion is checked against evidence, deviations from the GDD, the ADRs and the story's own scope are reported as facts, and the story is marked Complete only on the user's yes.

**Writes, after the user's yes:** the story file (`Status`, `Last Updated`, a `## Completion Notes` section) and its `production/sprint-status.yaml` entry; `docs/tech-debt-register.md` only when the user picks that option; at `minimal`, the brief's Features line the story finished; the story's row in its `EPIC.md`. The close question names each file it will change. The session checkpoint is written at the end of every run, whatever the verdict. **Next:** the next story (Phase 8). `/dev-story` and `/story-done` start only when the person types them, so never offer to start one as an option: print it as a line to type.

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: story found, facts and settings read
- [ ] Phase 2: what the story is checked against, loaded for its tier
- [ ] Phase 3: each criterion verified, traceability table built
- [ ] Phase 4: test evidence and run result checked
- [ ] Phase 5: deviations and scope checked; the AI's own calls kept or changed by the person
- [ ] Phase 6: review gates run, or their skip noted
- [ ] Phase 7: report and verdict shown; close asked
- [ ] Phase 8: next story named, checkpoint written, closing block printed

Phase 1: The story and its settings

**Which story.** The text typed after the skill name, with any `--review <mode>` pair removed, is the story path. With nothing typed:

1. The checkpoint in `production/session-state/active.md`: its **Current task** line, when it names a story. 2. Else the stories in progress: `bash .claude/scripts/story-facts.sh --all`, rows whose state is `IN_REVIEW` or `IN_PROGRESS`. Several: ask "Which story are we closing?" with one option per story. 3. None: ask for the path. When `production/epics/` holds no story file at all, stop: "No stories found in `production/epics/` — run `/create-stories [epic-slug]` to make them (at `standard` and `full`, run `/create-epics` first if there is no epic yet)."

**Its facts.** `bash .claude/scripts/story-facts.sh <story-path>` gives the status, type, layer, TR-IDs, ADRs, criteria count, test-evidence status and dependencies. Then read the story in full: the criteria text, the Test Evidence path, `## Files`, Out of Scope.

**Tier.** `workflow` for the story's system, keyed on the GDD filename stem of its `GDD:` path (`design/gdd/<stem>.md` → `<stem>`; the `[system]` of its TR-ID only when there is no GDD path): that system's `system_overrides` row if there is one, else the project value.

**What `qa.level` requires** (the evidence rows of `.claude/docs/coding-standards.md`). Take the value from the `qa.level` line above, never from `workflow` or `rigor`: the two are set apart, so `workflow: minimal` with `qa.level: standard` still requires a Logic story's unit test.

| Check | `qa.level: minimal` | `qa.level: standard` | `qa.level: full` | |---|---|---|---| | Logic, Integration test | waived | required | required | | Config/Data smoke report | waived | required, advisory by default | required, **blocking** by default | | Visual/Feel, UI retained screenshot | required | required | required | | Untested criteria (Phase 3) | never escalate | more than half block | **any** blocks |

The look is never waived: a Visual/Feel or UI story needs its screenshot at every level. **Gate level** per type is the `gate_level` line above. At `full`, a Config/Data default (`config=advisory(default…)`) becomes blocking; an explicit `testing.strict.config: false` still makes it advisory.

Phase 2: What the story is checked against

By the tier. Read every document by section, never whole.

• **`full`:** the current requirement text of each TR-ID: in

`docs/architecture/tr-registry.yaml`, the lines matching `id: <TR-ID>\s*$` and the entry's text below (the anchor keeps `TR-combat-001` from matching `TR-combat-0010`; `\s*` takes a Windows line ending). Never use text quoted in the story; the GDD's Acceptance Criteria and Detailed Design (`bash .claude/scripts/md-section.sh extract design/gdd/<file>.md "Acceptance Criteria"`, then the same for `"Detailed Design"`; exit 3: try `"Detailed Rules"`, the design standard's name for the same section); each ADR's status with `bash .claude/scripts/adr-status.sh <ADR ids>`, the