/story-readiness

name: story-readiness
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps. Use when user says 'is this story ready', 'can I start on this story', 'is story X ready to implement'."
argument-hint: "[story-file-path or 'all' or 'sprint']"
user-invocable: true
allowed-tools: Read, Glob, Grep, AskUserQuestion, Task
model: sonnet

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.
• If `Status: Proposed` → **BLOCKED**: the ADR may change before it is accepted,

and the story's implementation guidance could be wrong. Fix: `BLOCKED: ADR-NNNN is Proposed — wait for acceptance before implementing.`

• If the ADR file does not exist → **BLOCKED**: referenced ADR is missing.
• Auto-pass if story has an explicit "No ADR applies" N/A note.
• [ ] **TR-ID is valid and active**: If the story contains a `TR-[system]-NNN`

reference,