story-done skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,storygranularity,qa.level,testing.strict,systemoverrides

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

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

See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Workflow tier: resolved per the story's system (per .claude/docs/workflow-modes.md) — the GDD filename stem of the story's GDD: path (design/gdd/.md → ), with the [system] segment of its TR-[system]-NNN ID accepted only as a fallback alias: use the system_overrides row for that system if the block lists one, else the project value. It governs which Phase 4 deviation checks run — see Phase 4.

Workflow companion — modes.storygranularity (resolved above — supplied by modes.rigor unless set explicitly): cadence expectation only — story-done fires every 3–5 days at coarse, every 1–2 days at balanced, multiple times/day** at fine. It does not change any completion check.

qa.level: controls whether test evidence is required, where testing.strict controls whether a failure blocks and workflow controls which docs exist. modes.rigor sets qa.level and workflow together; set either explicitly to vary it alone. testing.strict is not fronted by rigor at all. At minimal, no evidence is required → skip the Test Evidence Requirement check (Phase 3), the >50%-untested traceability escalation, and the Phase 4b QA gate entirely; the acceptance-criteria verification still runs. At standard, the story's own type requires evidence; at full, every type does. testing.strict then decides whether present-but-failing evidence blocks. (rigor: minimal sets both; qa.level: minimal on its own leaves the workflow tier where it was.)

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:

look for stories marked IN PROGRESS.

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

1. If multiple in-progress stories are found, use AskUserQuestion:

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

1. 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:

(Grep pattern="id: " path="docs/architecture/tr-registry.yaml" outputmode="content" -A 6), not a full read of the registry. Read the current* requirement text from each matched 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).

• docs/architecture/tr-registry.yaml — grep the story's TR-IDs

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

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

sections, never an unbounded full read. Map headings first (Grep pattern="^## " path="docs/architecture/[adr-file].md" outputmode="content" -n), then bounded-Read only those two spans. This is the exact same content Phase 4 item 3's ADR constraints check needs — hold it here, do not re-read it there.

• The referenced ADR(s) — **just the ## Decision and ## Consequences

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

• docs/architecture/control-manifest.md header — extract the current

Phase 3: Verify Acceptance Criteria

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

Automatic verification (run without asking)

paths that should be in config files.

• 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

that should be in localization files.

• No hardcoded strings check: Grep for player-facing strings in the code root (resolve per .claude/docs/code-root-resolution.md). If the code root is unresolved, report NOT ASSESSED — code root unresolved rather than zero hits.

• 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:

directly verifies this criterion?

1. Ask: is there a test — unit, integration, or confirmed manual playtest — that

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

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

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

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

retained image under production/qa/evidence/[story-slug]/ shows it (the Run result: OBSERVED from /dev-story Phase 6 step 4), count that as covered — put the image path in the Test column. A visual criterion verified by looking is not UNTESTED; without this row every UI story reads as >50% untested and false-escalates.

• Retained screenshot: if the criterion names something on screen and a

1. 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] | production/qa/evidence/[slug]/01-shop-open.png | COVERED |
| AC-4: [criterion text] | — | UNTESTED |

evidence is required, so untested criteria never escalate):

1. Apply these escalation rules (skip entirely at qa.level: minimal — no

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