mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 13:01:50 +00:00
af2b864796
- New skill: /skill-test (static | spec | audit modes) - static: 7-check structural linter per skill file - spec: Claude-evaluated behavioral assertions against test specs - audit: coverage report across all 52 skills with priority gaps - New hook: validate-skill-change.sh — advisory reminder to lint after skill edits - New template: skill-test-spec.md — standard structure for authoring test specs - New: tests/skills/catalog.yaml — machine-readable coverage index (52 skills) - New: tests/skills/_fixtures/ — shared fixtures (complete concept, incomplete GDD) - New: 4 seed test specs for critical gate skills (gate-check, design-review, story-readiness, story-done) — 4 cases each - Modified: settings.json — validate-skill-change.sh added to PostToolUse hook Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
154 lines
6.0 KiB
Markdown
154 lines
6.0 KiB
Markdown
# 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).
|