/story-readiness

name: story-readiness
description: "Checks whether a story is ready to implement: clear acceptance criteria, no open questions, valid ADR and dependencies. Use when the user asks if a story, or the sprint's stories, are ready to start or build."
argument-hint: "[story-file-path or 'all' or 'sprint'] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-readiness/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/story-facts.sh *), Bash(bash .claude/scripts/adr-status.sh *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,qa.level,gate_level,story_granularity,system_overrides`

Resolved above — use as-is; `--review` overrides `review_mode`. No block → defaults in `.claude/docs/config-resolution.md`.

Ask with the question tool. Without one, list the options numbered and end your turn to wait. A skipped or dismissed question is not an answer: ask again in plain text.

Story Readiness

Checks that a story file holds everything a developer needs before writing code: no design questions mid-build, no guessing, no vague acceptance criteria.

**Read-only.** It never writes or edits a file. It reports, and offers to draft fixes in the conversation.

**Verdicts**, one per story. The first that matches wins, in this order:

1. **BLOCKED**: a finding the reader can clear. A referenced ADR is missing, `Proposed`, `Deprecated` or `Superseded`; a dependency story is missing or `Draft`; or a criterion holds an UNRESOLVED design question with no owner. 2. **NEEDS WORK**: a blocking checklist item fails. The story can be fixed now. 3. **NOT ASSESSED**: the story could not be evaluated. The file is unreadable, a referenced ADR has no readable `## Status`, or the design document it names cannot be found. Name what could not be read. It is never READY: a story nobody could check has not been shown ready. It ranks below the two failures, because a known blocker is more useful than an unknown. 4. **READY**: every item passes, is N/A with a reason, or is advisory. Advisory gaps are still listed.

Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided asks on major choices, autonomous logs and goes on; `automation_always_ask` categories always ask).

Phase 1: Scope

The scope is the text typed after the skill name, with any `--review <mode>` pair removed. What remains is one value; a path may contain spaces. With nothing typed, the story, epic or sprint the user's request names is the scope.

• **A story path**: that story.
• **`sprint`**: the stories the current sprint lists (Phase 2 reads them).
• **`all`**: every `story-*.md` under `production/epics/`.
• **An epic** (a slug or its folder): the `story-*.md` files in that folder.
• **Blank**: Ask: "What would you like to check?" Options: A specific story file /

All stories in the current sprint / All stories in production/epics/ / The stories of one epic.

**Zero stories in scope: stop with `NOT ASSESSED — no stories in scope`.** Name the scope and the path that was empty, and route to `/create-stories` (at `standard` and `full`, `/create-epics` first). Never print a `Ready: 0 / Needs Work: 0` summary over an empty list: it reads as a clean result. For `sprint`, "no sprint plan found" and "the sprint plan lists no stories" are different reports; say which.

Say "Checking [N] story files." before going on.

Phase 2: Facts, read once for the run

1. **Stories.** Run the story helper over the scope, with the `story_granularity` resolved above:

   bash .claude/scripts/story-facts.sh --lint --granularity <story_granularity> [--sprint | --all | <path> ...]

Each `STORY` row gives a story's status, type, layer, estimate, TR-IDs, ADRs, acceptance-criteria count, test-evidence line and dependencies. Each `LINT` row is a rule the story trips. Rows are observations; the verdict is yours. Exit 3 means a file was not found. With `NOT_FOUND` rows, each names a sprint `file:` entry or a path that is not a file: report each as a missing story and check the rest. With no `NOT_FOUND` row and `--sprint`, there is no `production/sprint-status.yaml`: report "no sprint plan found". Read each story file too: the testability, scope and asset items below need its words. 2. **ADRs.** One call gives every ADR's status and layer: `bash .claude/scripts/adr-status.sh`. A `no_status` or `UNFILLED` status is a malformed ADR: never treat an absent status as a failed one (route: `/architecture-decision retrofit [file]`). An ADR a story cites with no row is missing. 3. **Control manifest.** Only its `Manifest Version` line in `docs/architecture/control-manifest.md`. Missing file: note it once. 4. **TR registry.** Look up each story's TR-IDs, with their `status`, in `docs/architecture/tr-registry.yaml`. Missing file: note it once; the TR-ID item passes for every story. 5. **Sprint priority** (`sprint` scope): which stories are Must Have and Should Have, from the newest plan in `production/sprints/`.

**Tier per story.** `workflow` is resolved per story: use the `system_overrides` row for the story's system (the GDD filename stem of its `GDD:` path; the `[system]` of a `TR-[system]-NNN` ID only when there is no GDD path), else the project value. Stories in one run can sit at different tiers.

Phase 3: The checklist

Check every item for every story. The tier decides which groups block:

| Group | `full` | `standard` | `minimal` | |---|---|---|---| | Design Completeness | blocks | blocks | blocks; `design/game-brief.md` stands in for the GDD | | Architecture Completeness | blocks | the ADR status item blocks; the rest advisory unless it concerns a critical ADR | N/A, except the ADR status item | | Scope Clarity | blocks | blocks | blocks, except Estimate: advisory (no sprint p