Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/readiness/story-done.md

Skill Test Spec: /story-done

Skill Summary

/story-done closes the loop between design and implementation. Run at the end of implementing a story, it reads the story file, re-reads the current requirement text from docs/architecture/tr-registry.yaml (never the story's quoted copy) and the governing ADR's ## Decision / ## Consequences, verifies each acceptance criterion (automatically, by batched AskUserQuestion, or as DEFERRED — requires playtest session), builds a criterion-to-test traceability table, checks test evidence, and checks GDD/ADR/manifest/scope deviations (categorised BLOCKING / ADVISORY / OUT OF SCOPE). Review mode then decides the QA coverage gate (QL-TEST-COVERAGE) and the code review step (LP-CODE-REVIEW in full, a /code-review question in lean, a noted skip in solo). It produces a COMPLETE / COMPLETE WITH NOTES / NOT ASSESSED / BLOCKED verdict and, only after an AskUserQuestion choice, updates the story file, optionally appends to docs/tech-debt-register.md, and surfaces the next story — with no sprint plan, from bash .claude/scripts/story-status.sh, the list /help and /sprint-status read, run after the story file is written. It says what a screenshot shows only after opening it, and asks about behaviour criteria rather than reading them off the code.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥5 phase headings (complex multi-phase skill)
• Contains verdict keywords: COMPLETE, COMPLETE WITH NOTES, NOT ASSESSED, BLOCKED
• allowed-tools includes Write/Edit, so ask-before-write language is present ("Use AskUserQuestion before writing anything" — covering the story file and the tech-debt register)
• Has a next-step handoff (surfaces next story from sprint)

---

Test Cases

Case 1: Happy Path — All acceptance criteria met, no deviations

Fixture:

• project.yaml sets modes.rigor: standard (→ workflow: standard, qa.level: standard, review_mode: lean) and engine.name: Godot, so tests/unit/ is the test root
• Story file at production/epics/core/story-light-pickup.md with:
  • Type: Logic and 3 acceptance criteria, all implemented as described: AC-1 "Picking up a light adds it to the inventory", AC-2 "A pickup at the carry limit is refused", AC-3 "The picked-up light leaves the world"
  • TR-light-001; the story quotes an older wording of the requirement, while tr-registry.yaml holds the current text, which the implementation matches
  • ADR: ADR-0003 (Accepted), whose guidance was followed
  • A ## Test Evidence section naming tests/unit/light/pickup_test.gd, which exists with one test per criterion — test_pickup_adds_to_inventory, test_pickup_refused_at_limit, test_pickup_removes_world_light — so every criterion maps to a test
  • Status: In Progress
• The /dev-story checkpoint in production/session-state/active.md names this story as Current task and carries Run result: OBSERVED — the light leaves the floor and the inventory count rises — production/qa/evidence/story-light-pickup/01-pickup.png; that image exists
• Implementation files listed in the story exist in the code root
• A sprint plan in production/sprints/ has other READY / NOT STARTED Must Have stories

Input: /story-done production/epics/core/story-light-pickup.md

Expected behavior:

1. Skill reads the story and extracts its fields
2. Skill greps tr-registry.yaml for TR-light-001 and uses that current text
3. Skill maps the ADR's headings and reads only ## Decision and ## Consequences
4. Skill verifies each criterion and builds the traceability table: AC-1..AC-3 each map to their test function, all COVERED
5. Test evidence found — reported as "Test file present at <path>" (existence, not a pass claim); the checkpoint's Run result: OBSERVED is noted with its retained path
6. No deviations
7. Phase 4b notes "QL-TEST-COVERAGE skipped — Lean mode."
8. Phase 5 (lean) asks "Code review is skipped in lean mode. Did you run /code-review on the implemented files?"
9. Completion report with verdict COMPLETE
10. AskUserQuestion "Verification complete. How do you want to proceed?"; on "Close the story", the file is updated
11. Skill surfaces the next ready stories from the sprint

Assertions:

• Requirement text comes from tr-registry.yaml, not the story's stale quote — the wording difference produces no deviation
• Skill reads only the ADR's ## Decision and ## Consequences spans, not the whole file
• Each criterion is listed with its status (auto-verified / confirmed / FAILS / DEFERRED) and appears in a Criterion | Test | Status traceability table
• Test evidence is reported as present, without claiming the tests pass
• In lean mode the skill asks whether /code-review was run, and records the answer in the Completion Notes Code Review: line
• The traceability table maps each of AC-1..AC-3 to its test function, with no UNTESTED row
• The Run result: line is read from the checkpoint (whose Current task names this story) and noted with its retained path
• Verdict is COMPLETE — every criterion maps to a test, the run was observed and retained, and no deviations exist
• No file is edited before the Phase 7 AskUserQuestion; on "Close the story" the story gets Status: Complete, a Last Updated: date and a ## Completion Notes section
• After completion, skill surfaces the next READY / NOT STARTED Must Have or Should Have story from production/sprints/ and suggests /story-readiness [path]

---

Case 2: Criteria needing manual or playtest verification

Fixture:

• As Case 1, plus two more criteria:
  • (a) "Player sees correct animation on pickup" — no automated test; a frame of the animation is retained at production/qa/evidence/story-light-pickup/02-pickup-anim.png
  • (b) "Pickup state persists across a full level run" — needs a full game build
• 1 of the 5 criteria ends up with no covering test

Input: /story-done production/epics/core/story-light-pickup.md

Expected behavior:

1. Criterion (a) is a subjective/gameplay criterion → skill asks via a batched AskUserQuestion ("Does [criterion]?" — Yes — passes / No — fails / Not tested yet)
2. The user answers Yes — passes. The retained frame is the observation the evidence rule requires; the answer covers the motion a still cannot show, and counts as the manual test
3. Criterion (b) is marked DEFERRED — requires playtest session and does not block
4. The traceability table shows (b) UNTESTED; 1 of 5 (≤50%) → ADVISORY
5. The Completion Notes list the deferred item and "Untested criteria: [AC-N list]. Recommend adding tests in a follow-up story."

Assertions:

• Skill asks the user about the unverifiable criterion rather than assuming it passes, batching up to 4 such questions per call — a behaviour criterion is never marked verified from reading the code
• Before the report says what 02-pickup-anim.png shows, the image is opened with Read; the checkpoint's Run result: text is quoted as /dev-story's description, never restated as the skill's own observation
• The playtest-only criterion is marked DEFERRED — requires playtest session
• Verdict is COMPLETE WITH NOTES, and the report lists the DEFERRED criterion — neither BLOCKED nor NOT ASSESSED, since a DEFERRED criterion does not block and does not fire the NOT ASSESSED trigger
• The deferred criterion is named in the Completion Notes Criteria: line, with the untested-criteria recommendation
• Variant — if the user answers No — fails for (a), the criterion is FAILS, the verdict is BLOCKED, and the skill does not proceed to Phase 7 on its own
• Variant — no image for this story is retained under production/qa/evidence/ and the checkpoint carries no Run result: line: the user's Yes — passes for (a) is an assertion, not evidence, so the missing observation is flagged at the Logic gate level (BLOCKING by default) and the verdict is BLOCKED — never COMPLETE WITH NOTES on the confirmation alone
• Skill still asks via AskUserQuestion before updating the story file

---

Case 3: Blocked Path — GDD deviation detected

Fixture:

• project.yaml sets modes.workflow: full
• The current tr-registry.yaml text for the story's TR-ID: "Player can carry max 3 light sources"
• Implementation in the code root has MAX_CARRIED_LIGHTS = 5 in gameplay code

Input: /story-done production/epics/core/story-light-pickup.md

Expected behavior:

1. The GDD rules check (against the current registry text) finds the implementation contradicts "max 3"
2. The hardcoded-values check also flags the gameplay literal that belongs in a data file
3. The contradiction is categorised BLOCKING and cited with its GDD/TR reference
4. Verdict BLOCKED; skill lists what must be fixed and offers to help, and does not advance to Phase 7 on its own
5. If the user explicitly asks to close anyway, the Phase 7 menu appears (always asked, even in autonomous mode — scope_changes)

Assertions:

• Skill detects the mismatch between the current requirement text and the implemented value
• The deviation is reported neutrally as BLOCKING with the GDD/TR reference — the skill does not edit code or the GDD to reconcile it
• Verdict is BLOCKED, and Phase 7 is not entered unless the user explicitly asks to close anyway
• Closing a BLOCKED story goes through the Phase 7 AskUserQuestion regardless of automation mode
• If closed via "Accept deviations as-is and close anyway", the deviation is recorded in the Completion Notes Deviations: line

---

Case 4: Edge Case — No argument, auto-detect current story

Fixture:

• production/session-state/active.md names production/epics/core/story-oxygen-drain.md as the active story
• That story file exists with Status: In Progress

Input: /story-done (no argument)

Expected behavior:

1. Skill reads production/session-state/active.md and takes the active story
2. Skill reads that story file and proceeds normally
3. The completion report's **Story**: line names the auto-detected path
4. If active.md names no story, skill reads the newest sprint plan for IN PROGRESS stories; with several, it asks "Which story are we completing?"; with none, it asks for the path

Assertions:

• Skill reads production/session-state/active.md first when no argument is given
• The report's **Story**: line names the auto-detected story file
• With several in-progress stories in the sprint, skill asks which one via AskUserQuestion instead of picking one
• If no story is found anywhere, skill asks the user to provide a path

---

Case 5: Director Gate — LP-CODE-REVIEW across review modes

Fixture:

• project.yaml sets modes.workflow: full and qa.level: standard (so the QA coverage gate is not skipped for qa.level: minimal)
• Story file at production/epics/core/story-light-pickup.md, Type: Logic
• All acceptance criteria verified, no GDD deviations, implementation files exist, and Case 1's run evidence (the Run result: OBSERVED checkpoint and its retained image)
• Review mode comes from modes.review_mode (legacy mirror production/review-mode.txt) or --review

Case 5a — full mode: /story-done production/epics/core/story-light-pickup.md --review full

Expected behavior:

1. After Phases 3–4, skill spawns qa-lead with gate QL-TEST-COVERAGE (unless qa.level: minimal or a Config/Data story)
2. Skill spawns lead-programmer with gate LP-CODE-REVIEW, passing the implementation file paths, story path, relevant GDD section and governing ADR
3. The verdict (APPROVE / CONCERNS / REJECT) is presented to the user
4. CONCERNS → AskUserQuestion: Revise flagged issues / Accept and proceed / Discuss further
5. REJECT → no Phase 6 verdict until the issues are resolved
6. NOT ASSESSED (a gate input was missing) → the skill names the missing input and never reads it as APPROVE: the input is supplied and the gate re-run, or the Phase 6 verdict is at best NOT ASSESSED

Assertions (5a):

• Skill uses the resolved review mode before deciding whether to spawn LP-CODE-REVIEW
• LP-CODE-REVIEW is spawned in full mode after the implementation checks, with the four context items
• A REJECT verdict prevents the story from reaching a COMPLETE verdict until resolved
• A CONCERNS verdict produces the three-option AskUserQuestion
• A NOT ASSESSED answer from either gate is never treated as APPROVE / ADEQUATE: unless the missing input is supplied and the gate re-run, the verdict is NOT ASSESSED, not COMPLETE
• Skill still asks via the Phase 7 AskUserQuestion before updating story status, even after APPROVE

Case 5b — lean mode: --review lean

Assertions (5b):

• LP-CODE-REVIEW does NOT spawn
• Skill asks "Did you run /code-review on the implemented files?" with the three listed options; all three proceed
• "QL-TEST-COVERAGE skipped — Lean mode." is noted

Case 5c — solo mode: --review solo

Assertions (5c):

• Neither LP-CODE-REVIEW nor QL-TEST-COVERAGE spawns, and no code-review question is asked
• Output notes "LP-CODE-REVIEW skipped — Solo mode." and "QL-TEST-COVERAGE skipped — Solo mode."
• Skill still requires the Phase 7 AskUserQuestion before marking the story Complete

---

Case 6: UI story at minimal, no sprint plan — the screenshot closes it

Fixture:

• project.yaml sets modes.rigor: minimal (→ workflow: minimal, qa.level: minimal, review_mode: solo); there is no sprint plan in production/sprints/ — the brief's build order is the plan
• production/epics/mvp/ holds story-001-*.md (Status: Complete), this story story-002-shop-panel.md (Status: In Progress) and story-003-*.md (Status: Ready)
• story-002-shop-panel.md has Type: UI and two criteria: "The shop panel shows all 6 item slots inside the frame at 1280x720" and "Each slot shows its price"
• production/qa/evidence/story-002-shop-panel/01-shop-open.png exists and shows both; the checkpoint carries Run result: OBSERVED with that path; there is no evidence doc and no sign-off

Input: /story-done production/epics/mvp/story-002-shop-panel.md

Expected behavior:

1. At qa.level: minimal the Logic, Integration and Config/Data evidence checks, the >50%-untested escalation and Phase 4b are skipped ("QL-TEST-COVERAGE skipped — qa.level minimal.") — but the UI screenshot check runs
2. The retained screenshot satisfies the UI gate; no evidence doc or sign-off is asked for
3. Phase 4 runs the manifest, hardcoded-value and scope checks only (no GDD/ADR traceability at minimal); Phase 5 notes "LP-CODE-REVIEW skipped — Solo mode."
4. Verdict COMPLETE; after the Phase 7 approval the story is marked Complete
5. Phase 8 takes the no-sprint branch: it runs bash .claude/scripts/story-status.sh after the story file is written; story-003 is on its first TODO line → "Run /dev-story [path]"

Assertions:

• The UI screenshot check runs at qa.level: minimal and is satisfied by the retained image alone — no evidence doc or sign-off is required for a UI story
• Verdict is COMPLETE, not BLOCKED for a missing sign-off
• Phase 8 names story-003 and recommends /dev-story directly — no /story-readiness line at minimal, and no Sprint Close-Out Sequence
• The next story comes from bash .claude/scripts/story-status.sh, run after this story's Status: Complete is written — not from a grep of one epic folder
• Variant — production/epics/combat/story-001-arena.md reads **Status:** In Review: it is Next Up (the script lists IN_REVIEW first, across every epic folder), and the Next Up line recommends /story-done [path] to close it, not /dev-story
• Variant — no image under production/qa/evidence/ and no Run result: line: the UI gate is still BLOCKING at qa.level: minimal, so the verdict is BLOCKED
• Variant — story-003 is Blocked, naming its blocker, and no other story is unfinished: Phase 8 prints no Next Up, names story-003 with its blocker, suggests clearing it, and never says the build order is done

---

Case 7: NOT ASSESSED — a criterion nobody could evaluate

Fixture:

• As Case 1, plus a fourth criterion, AC-4: "The pickup code is robust" — it names no observable outcome, so no test, run or playtest could settle it

Input: /story-done production/epics/core/story-light-pickup.md

Expected behavior:

1. AC-1..AC-3 verify as in Case 1
2. AC-4 cannot be evaluated at all — not DEFERRED (no session could settle it as written) and not failed
3. Verdict NOT ASSESSED, naming AC-4 and what would make it checkable (rewrite it as an observable condition)
4. The skill does not proceed to Phase 7 on its own

Assertions:

• Verdict is NOT ASSESSED — not COMPLETE or COMPLETE WITH NOTES, and not BLOCKED (nothing is known to fail)
• Output names AC-4, why it cannot be evaluated, and what would make it checkable
• Phase 7 is entered only if the user explicitly asks to close anyway; it then always prompts (scope_changes), and the Completion Notes record AC-4 as never evaluated
• Variant — AC-4 is a checkable criterion that the user answers Not tested yet: it is UNTESTED in the traceability table and the verdict is NOT ASSESSED, naming what would settle it
• Variant — another criterion also FAILS: the verdict is BLOCKED (BLOCKED is evaluated before NOT ASSESSED)

---

Protocol Compliance

• Asks via AskUserQuestion before updating the story file
• Appends to docs/tech-debt-register.md only when the user picks "Close and log advisory deviations as tech debt", as rows of /tech-debt's register table with an Added date — never as free bullets
• Presents the complete report (criteria, traceability, test evidence, deviations, scope) before asking
• Ends by surfacing the next ready story (sprint plan) or the next story in the epic folder (no sprint plan)
• Never closes a BLOCKED or NOT ASSESSED story on its own — only on the user's explicit request, through Phase 7
• Never skips code review silently: full spawns LP-CODE-REVIEW, lean asks, solo notes the skip

---

Coverage Notes

• The full 8-phase flow of the skill is exercised across Cases 1-3; not all edge cases within each phase are covered.
• Tech debt logging (docs/tech-debt-register.md) is covered only through the Phase 7 option and the row-format line in Protocol Compliance; no case writes a row.
• The production/sprint-status.yaml update and the session-state checkpoint (both silent, after the Phase 7 approval) are not primary assertions.
• Case 6 covers the no-sprint-plan branch at minimal; the Sprint Close-Out Sequence is not tested here.
• Stories with multiple TR-IDs or multiple ADRs are not explicitly tested.