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

Skill Test Spec: /story-readiness

Skill Summary

/story-readiness validates that a story file is ready for a developer to pick up and implement. It loads its reference context once (systems index, the control manifest's Manifest Version: header, the TR registry, and every ADR's status via a single Grep), then evaluates each story against six checklist groups: Design Completeness, Architecture Completeness, Scope Clarity, Open Questions, Asset References, and Definition of Done. The workflow tier resolved for the story's system decides which groups block (full: all; standard: architecture items advisory except a critical ADR; minimal: architecture N/A) — except one rule at every tier: an ADR the story references that is missing, Proposed, Deprecated or Superseded BLOCKS, because /dev-story stops on it. At minimal, design/game-brief.md stands in for the GDD. It produces a READY / NEEDS WORK / BLOCKED / NOT ASSESSED verdict. It is read-only — it never writes or edits a file. In full review mode it then runs the QL-STORY-READY gate (qa-lead).

A fixture that sets neither qa.level nor modes.rigor resolves qa.level: minimal (the rigor: minimal default). There the evidence item auto-passes for Logic, Integration and Config/Data stories — never for UI or Visual/Feel, whose retained screenshot is required at every qa.level (Case 6).

---

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 ≥2 phase headings or numbered check sections
• Contains verdict keywords: READY, NEEDS WORK, BLOCKED, NOT ASSESSED
• Does NOT require "May I write" language — allowed-tools has no Write or Edit
• Has a next-step handoff (what to do after verdict)

---

Test Cases

Case 1: Happy Path — Fully ready story

Fixture:

• project.yaml sets modes.workflow: full and modes.review_mode: solo
• Story file exists at production/epics/core/story-light-pickup.md containing:
  • A GDD: design/gdd/light-system.md reference quoting the specific requirement
  • TR-light-001, present with status: active in docs/architecture/tr-registry.yaml
  • ADR: ADR-0003; docs/architecture/adr-0003-inventory.md has ## Status Accepted
  • Type: Logic, an ## Acceptance Criteria section with 3 testable items, and a ## Test Evidence section naming the test path
  • An estimate, an Out of Scope statement, and Dependencies: None
  • Engine notes (or "N/A — no engine API involved"), the relevant manifest rules, and a performance note
  • A Manifest Version: equal to the one in docs/architecture/control-manifest.md
  • No TBD / UNRESOLVED markers and no asset paths
• A sprint plan in production/sprints/ lists other stories

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

Expected behavior:

1. Skill reports "Validating 1 story files."
2. Skill loads context once: greps Manifest Version from the control manifest, indexes tr-registry.yaml, and resolves every ADR status with one Grep pattern="^## Status" glob="docs/architecture/adr-*.md" scan
3. Skill evaluates all six checklist groups
4. Skill outputs READY with all checks passing
5. Phase 8 notes "QL-STORY-READY skipped — Solo mode."
6. Section 7 surfaces other ready stories from the sprint

Assertions:

• ADR status is resolved from the one-scan ^## Status Grep over docs/architecture/adr-*.md, not by reading each ADR in full, and ADR-0003 is found Accepted
• Skill looks up TR-light-001 in tr-registry.yaml and finds it active
• The current manifest version is taken from a Grep of the manifest header, not a full read
• The "Passing Checks (N/[total])" section names all six groups — Design Completeness, Architecture Completeness, Scope Clarity, Open Questions, Asset References ("no asset references"), Definition of Done — with the passing items under each
• Verdict is READY when all checks pass
• Skill does not write any files
• Section 7 lists up to 3 other ready sprint stories — or states "Next ready stories: no sprint file found" / "none ready in [sprint]" rather than omitting the section

---

Case 2: Blocked Path — Referenced ADR is Proposed (not Accepted)

Fixture:

• project.yaml sets modes.workflow: full
• Story production/epics/core/story-light-system.md references ADR-0005
• docs/architecture/adr-0005-light-system.md exists with ## Status Proposed
• All other story content is complete

Input: /story-readiness production/epics/core/story-light-system.md

Expected behavior:

1. The status scan finds ADR-0005 Proposed
2. Skill flags it BLOCKED with the fix text "BLOCKED: ADR-0005 is Proposed — wait for acceptance before implementing."
3. Skill outputs BLOCKED, listing the ADR under Blockers

Assertions:

• Verdict is BLOCKED (not NEEDS WORK or READY) when the ADR is Proposed at full
• Output explicitly names ADR-0005 as the blocker
• Output says to wait for the ADR's acceptance before implementing
• Skill does not output READY regardless of other checks passing
• Variant — same story at modes.workflow: standard, with | **Layer** | Feature | in ADR-0005's ## Engine Compatibility table (non-critical): the story references the Proposed ADR, so the verdict is still BLOCKED — a referenced Proposed ADR blocks at every tier, because /dev-story stops on it
• Variant — the same non-critical ADR at standard, now Accepted, with the story's Manifest Version: older than the control manifest's: the stale version is listed under Gaps as advisory, with its Fix: line, and the verdict is READY — an advisory gap does not downgrade it

---

Case 3: Needs Work — Missing Acceptance Criteria (checked at every tier)

Fixture:

• project.yaml sets modes.workflow: minimal
• Story production/epics/core/story-oxygen-drain.md has Type: Logic but no ## Acceptance Criteria section
• The story references no ADR, no TR-ID and no manifest version

Input: /story-readiness production/epics/core/story-oxygen-drain.md

Expected behavior:

1. At minimal, skill evaluates Design Completeness and Scope Clarity and treats Architecture Completeness as N/A
2. Skill finds no acceptance criteria
3. Skill outputs NEEDS WORK, naming the gap with a Fix: line suggesting specific, observable criteria

Assertions:

• Verdict is NEEDS WORK (not BLOCKED or READY) when the Acceptance Criteria section is absent
• Output identifies the missing Acceptance Criteria specifically, with a Fix: line proposing measurable criteria
• No ADR, TR-ID or manifest gap is flagged — Architecture Completeness is N/A at minimal
• The story is not BLOCKED: nothing requires outside action (no missing/DRAFT dependency, no unowned UNRESOLVED question)
• Variant — the same minimal story with acceptance criteria traced to design/game-brief.md's MVP feature (no design/gdd/ path): "GDD requirement referenced" passes — the brief stands in for the GDD at minimal
• Variant — the story also names ADR-0005, whose ## Status is Proposed: the verdict is BLOCKED at minimal too — the referenced-ADR rule is the one Architecture Completeness item that is not N/A

---

Case 4: Edge Case — Stale manifest version

Fixture:

• project.yaml sets modes.workflow: full
• Story has Manifest Version: 2026-01-15 in its header
• docs/architecture/control-manifest.md has Manifest Version: 2026-03-10
• Everything else in the story passes

Input: /story-readiness production/epics/core/story-mirror-rotation.md

Expected behavior:

1. Skill extracts 2026-01-15 from the story
2. Skill greps the manifest header and extracts 2026-03-10
3. The story's version is older → the "Manifest version is current" item fails
4. Verdict is NEEDS WORK, with the fix to review the changed rules and update the story's Manifest Version:

Assertions:

• Skill gets the current version by grepping Manifest Version in docs/architecture/control-manifest.md
• Skill compares the story's embedded version against the current one
• At full, a stale manifest version results in NEEDS WORK (not BLOCKED, not READY)
• Output explains that new manifest rules may apply, and the Fix: says to review the changed rules, update the story if needed, then set its Manifest Version: to current

---

Case 5: Director Gate — QL-STORY-READY behavior across review modes

Fixture:

• project.yaml sets modes.workflow: full
• Story file exists and passes every checklist item
• Review mode comes from modes.review_mode (legacy mirror production/review-mode.txt) or --review

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

Expected behavior:

1. Skill completes its own checklist and verdict first
2. Skill spawns qa-lead via Agent with gate QL-STORY-READY, passing the story file path, story type, acceptance criteria (verbatim), the GDD requirement (TR-ID and text), dependency status and the Phase 4 verdict
3. ADEQUATE → story cleared
4. GAPS → AskUserQuestion: Update story with suggested gaps / Accept and proceed anyway / Discuss further
5. INADEQUATE → the gate says the story must be revised before sprint inclusion: the checklist's READY is demoted to NEEDS WORK and the final verdict line is restated with the gaps; the user is asked whether to update the story or proceed anyway, and proceeding is recorded as an override, not as READY
6. NOT ASSESSED (a gate input was missing) → the missing input is named and never read as ADEQUATE: it is supplied and the gate re-run, or READY becomes NOT ASSESSED

Assertions (5a):

• Skill uses the resolved review mode before deciding whether to spawn QL-STORY-READY
• QL-STORY-READY is spawned only after the checklist verdict exists
• A GAPS result produces the three-option AskUserQuestion
• An INADEQUATE result overrides the checklist's READY: the final verdict is NEEDS WORK, restated with the gate's specific gaps
• If the user proceeds anyway, the verdict stays NEEDS WORK and the output states the override ("proceeding despite QL-STORY-READY: INADEQUATE (user override)") — never a silent READY
• A NOT ASSESSED answer from the gate names the missing input and never leaves READY standing: unless the input is supplied and the gate re-run, the verdict is NOT ASSESSED

Case 5b — lean or solo mode: --review lean or --review solo

Expected behavior:

1. QL-STORY-READY is skipped
2. Output notes "QL-STORY-READY skipped — Lean mode." or "QL-STORY-READY skipped — Solo mode."
3. Verdict is based on the checklist only

Assertions (5b):

• QL-STORY-READY does NOT spawn in lean or solo mode
• The skip is noted in the output with the mode named
• Verdict is based on the checklist alone

---

Case 6: UI story at qa.level: minimal — the screenshot plan is never waived

Fixture:

• project.yaml sets modes.workflow: standard and qa.level: minimal (set on its own, so only the test-evidence axis is at minimal and every checklist group is evaluated)
• No docs/architecture/control-manifest.md and no tr-registry.yaml yet
• Story production/epics/ui/story-003-shop-panel.md has Type: UI, a GDD: design/gdd/shop.md reference quoting the requirement it implements, two testable acceptance criteria naming what the shop panel shows, "No ADR applies — pure layout", engine notes, an estimate, an Out of Scope statement, Dependencies: None and a performance note — and no ## Test Evidence section, nor any other mention of where a screenshot will go
• No TBD / UNRESOLVED markers and no asset paths

Input: /story-readiness production/epics/ui/story-003-shop-panel.md

Expected behavior:

1. The architecture items pass or auto-pass (explicit "No ADR applies"; no TR-ID, manifest version or manifest to check)
2. The "Test evidence requirement is clear" item still applies — UI is the exception to the qa.level: minimal auto-pass
3. testing.strict.ui is unset, so the item is strict by default: the missing section makes the story NEEDS WORK
4. The Fix: asks for a ## Test Evidence section naming where the retained screenshot of each screen touched will go under production/qa/evidence/

Assertions:

• Verdict is NEEDS WORK, not READY — the evidence item does not auto-pass for a UI story at qa.level: minimal
• The gap names the missing screenshot plan, and its Fix: points at production/qa/evidence/
• The missing screenshot plan is the only gap — no ADR, TR-ID or manifest gap is flagged
• Variant — a Type: Logic story with three testable criteria and no ## Test Evidence section, same config: the evidence item auto-passes at qa.level: minimal, so the missing section alone does not make it NEEDS WORK

---

Case 7: NOT ASSESSED — nothing to evaluate, or an ADR nobody can read

Case 7a — zero stories in scope:

• production/epics/ holds only EPIC.md index files, no story files
• Input: /story-readiness all

Assertions (7a):

• Output is NOT ASSESSED — no stories in scope, naming production/epics/**/*.md as the path searched
• It routes to /create-epics [layer] then /create-stories [epic-slug]
• No Ready: 0 / Needs Work: 0 / Blocked: 0 summary is printed over an empty list

Case 7b — a referenced ADR with no readable status:

• project.yaml sets modes.workflow: full
• Story production/epics/core/story-save-slots.md passes every other item and references ADR-0007; docs/architecture/adr-0007-save-format.md exists but has no ## Status section
• Input: /story-readiness production/epics/core/story-save-slots.md

Assertions (7b):

• The ADR check is NOT ASSESSED — the status is unknown, not failed — and the verdict is NOT ASSESSED: not BLOCKED, not READY
• Output names docs/architecture/adr-0007-save-format.md and routes to /architecture-decision retrofit docs/architecture/adr-0007-save-format.md
• Variant — the story names ADR-0007 but no such file exists: that is a finding about the story, so the verdict is BLOCKED ("referenced ADR is missing"), not NOT ASSESSED

---

Protocol Compliance

• Does NOT use Write or Edit tools; any help filling gaps is drafted in conversation only
• Single-story output follows the Section 5 template: Verdict line, "Passing Checks (N/[total])", Gaps each with a Fix: line, and Blockers when BLOCKED
• Does not ask for write approval (no file writes)
• Ends with a recommended next step (fix the gaps, or /dev-story [story-path] once READY)
• Keeps the verdict levels distinct — NOT ASSESSED (could not evaluate) is never reported as BLOCKED

---

Coverage Notes

• A TR-ID missing from the registry follows the same NEEDS WORK pattern as Case 4.
• The zero-story scope is Case 7a; the sprint / all aggregate output over real stories and the Must Have sprint escalation warning are not tested here.
• The no-argument path (scope chosen via AskUserQuestion) is not tested.
• Stories with multiple ADR references are not tested; behavior is assumed to be additive (all ADRs must be Accepted for READY verdict).