Story Readiness

This skill validates that a story file contains everything a developer needs to begin implementation — no mid-sprint design interruptions, no guessing, no ambiguous acceptance criteria. Run it before assigning a story.

This skill is read-only. It never edits story files. It reports findings and asks whether the user wants help filling gaps.

Output: Verdict per story (READY / NEEDS WORK / BLOCKED) with a specific gap list for each non-ready story.

Phase 0: Resolve Review Mode

Resolve the review mode once at startup (store for all gate spawns this run):

1. If skill was called with --review [full|lean|solo] → use that value
2. Else read production/review-mode.txt → use that value
3. Else → default to lean

See .claude/docs/director-gates.md for the full check pattern and mode definitions.

1. Parse Arguments

Scope: $ARGUMENTS[0] (blank = ask user via AskUserQuestion)

• Specific path (e.g., /story-readiness production/epics/combat/story-001-basic-attack.md): validate that single story file.
• sprint: read the current sprint plan from production/sprints/ (most recent file), extract every story path it references, validate each one.
• all: glob production/epics/**/*.md, exclude EPIC.md index files, validate every story file found.
• No argument: ask the user which scope to validate.

If no argument is given, use AskUserQuestion: - "What would you like to validate?" - Options: "A specific story file", "All stories in the current sprint", "All stories in production/epics/", "Stories for a specific epic"

Report the scope before proceeding: "Validating [N] story files."

2. Load Supporting Context

Before checking any stories, load reference documents once (not per-story):

• design/gdd/systems-index.md — to know which systems have approved GDDs
• docs/architecture/control-manifest.md — to know which manifest rules exist (if the file does not exist, note it as missing once; do not re-flag per story) Also extract the Manifest Version: date from the header block if the file exists.
• docs/architecture/tr-registry.yaml — index all entries by id. Used to validate TR-IDs in stories. If the file does not exist, note it once; TR-ID checks will auto-pass for all stories (registry predates stories, so missing registry means stories are from before TR tracking was introduced).
• All ADR status fields — for each unique ADR referenced across the stories being checked, read the ADR file and note its Status: field. Cache these so you don't re-read the same ADR for every story.
• The current sprint file (if scope is sprint) — to identify Must Have / Should Have priority for escalation decisions

3. Story Readiness Checklist

For each story file, evaluate every item below. A story is READY only if all items pass or are explicitly marked N/A with a stated reason.

Design Completeness

• [ ] GDD requirement referenced: The story includes a design/gdd/ path and quotes or links a specific requirement, acceptance criterion, or rule from that GDD — not just the GDD filename. A link to the document without tracing to a specific requirement does not pass.
• [ ] Requirement is self-contained: The acceptance criteria in the story are understandable without opening the GDD. A developer should not need to read a separate document to understand what DONE means.
• [ ] Acceptance criteria are testable: Each criterion is a specific, observable condition — not "implement X" or "the system works correctly". Bad example: "Implement the jump mechanic." Good example: "Jump reaches max height of 5 units within 0.3 seconds when jump is held."
• [ ] No acceptance criteria require judgment calls (auto-pass for Type: Visual/Feel): Criteria like "feels responsive" or "looks good" are not testable without a defined benchmark. For Logic, Integration, UI, and Config/Data stories, these must be replaced with specific observable conditions. For Visual/Feel stories, subjective criteria are expected and this check auto-passes — instead verify that each subjective criterion has a paired playtest protocol or evidence requirement (e.g., "evidence doc required at production/qa/evidence/[slug]-evidence.md"). PASS if the acceptance criterion ends with or is accompanied by an explicit reference to a file path such as production/qa/evidence/[slug]-evidence.md. NEEDS WORK if the criterion is purely subjective with no evidence file path specified.

Architecture Completeness

• [ ] ADR referenced or N/A stated: The story references at least one ADR, OR explicitly states "No ADR applies" with a brief reason. A story with no ADR reference and no explicit N/A note fails this check.
• [ ] ADR is Accepted (not Proposed): For each referenced ADR, check its Status: field using the cached ADR statuses loaded in Section 2.
• If Status: Accepted → pass