Claude-Code-Game-Studios/tests/skills/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 checks four dimensions: Design (embedded GDD requirements), Architecture (ADR references and status), Scope (clear boundaries and DoD), and Definition of Done (testable criteria). It produces a READY / NEEDS WORK / BLOCKED verdict. It is a read-only skill and runs before any developer picks up a story.

---

Static Assertions (Structural)

Verified automatically by /skill-test static — 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
• Does NOT require "May I write" language (read-only skill)
• Has a next-step handoff (what to do after verdict)

---

Test Cases

Case 1: Happy Path — Fully ready story

Fixture:

• Story file exists at production/epics/core/story-light-pickup.md
• Story contains:
  • TR-ID: TR-light-001 (GDD requirement reference)
  • ADR: docs/architecture/adr-003-inventory.md
  • Referenced ADR exists and has status Accepted
  • Referenced TR-ID exists in docs/architecture/tr-registry.yaml
  • Story has ## Acceptance Criteria with ≥3 testable items
  • Story has ## Definition of Done section
  • Story has Status: Ready for Dev
  • Manifest version in story header matches current docs/architecture/control-manifest.md

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

Expected behavior:

1. Skill reads the story file
2. Skill reads the referenced ADR — verifies status is Accepted
3. Skill reads docs/architecture/tr-registry.yaml — verifies TR-ID exists
4. Skill reads docs/architecture/control-manifest.md — verifies manifest version matches
5. Skill evaluates all 4 dimensions (Design, Architecture, Scope, DoD)
6. Skill outputs READY verdict with all checks passing

Assertions:

• Skill reads the referenced ADR file (not just the story)
• Skill verifies ADR status is Accepted (not Proposed)
• Skill reads tr-registry.yaml to verify TR-ID exists
• Output includes check results for all 4 dimensions
• Verdict is READY when all checks pass
• Skill does not write any files

---

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

Fixture:

• Story file exists with ADR: docs/architecture/adr-005-light-system.md
• adr-005-light-system.md exists but has Status: Proposed
• All other story content is otherwise complete

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

Expected behavior:

1. Skill reads the story
2. Skill reads adr-005-light-system.md — finds Status: Proposed
3. Skill flags this as a BLOCKING issue (cannot implement against unaccepted ADR)
4. Skill outputs BLOCKED verdict
5. Skill recommends: accept or reject the ADR before picking up the story

Assertions:

• Verdict is BLOCKED (not NEEDS WORK or READY) when ADR is Proposed
• Output explicitly names the Proposed ADR as the blocker
• Output recommends resolving ADR status before proceeding
• Skill does not output READY regardless of other checks passing

---

Case 3: Needs Work — Missing Acceptance Criteria

Fixture:

• Story file exists but has no ## Acceptance Criteria section
• ADR reference exists and is Accepted
• TR-ID exists in registry
• Manifest version matches

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

Expected behavior:

1. Skill reads the story
2. Skill finds no Acceptance Criteria section
3. Skill flags this as a NEEDS WORK issue (story is incomplete, not blocked)
4. Skill outputs NEEDS WORK verdict
5. Skill names the missing section and suggests adding measurable criteria

Assertions:

• Verdict is NEEDS WORK (not BLOCKED or READY) when Acceptance Criteria section is absent
• Output identifies the missing Acceptance Criteria section specifically
• Output suggests adding testable/measurable criteria
• Skill distinguishes NEEDS WORK (fixable without external dependencies) from BLOCKED (requires outside action)

---

Case 4: Edge Case — Stale manifest version

Fixture:

• Story file has Manifest Version: 2026-01-15 in its header
• docs/architecture/control-manifest.md has Manifest Version: 2026-03-10
• Versions do not match (story was created before manifest was updated)

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

Expected behavior:

1. Skill reads the story and extracts manifest version 2026-01-15
2. Skill reads control manifest header and extracts current version 2026-03-10
3. Skill detects version mismatch
4. Skill flags this as an ADVISORY issue (not blocking, but worth noting)
5. Verdict is NEEDS WORK with manifest staleness noted

Assertions:

• Skill reads docs/architecture/control-manifest.md to get current version
• Skill compares story's embedded manifest version against current manifest version
• Stale manifest version results in NEEDS WORK (not BLOCKED, not READY)
• Output explains that the story's embedded guidance may be outdated

---

Protocol Compliance

• Does NOT use Write or Edit tools (read-only skill)
• Presents complete check results before verdict
• Does not ask for approval (no file writes)
• Ends with recommended next step (fix issues or proceed to implementation)
• Distinguishes three verdict levels clearly (READY vs NEEDS WORK vs BLOCKED)

---

Coverage Notes

• Case where TR-ID is missing from the registry entirely is not explicitly tested here; it follows the same NEEDS WORK pattern as Case 3.
• The "no argument" path (skill auto-detecting the current story) is not tested because it depends on production/session-state/active.md content, which is hard to fixture reliably.
• Stories with multiple ADR references are not tested; behavior is assumed to be additive (all ADRs must be Accepted for READY verdict).