!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:

An advisory item that fails is listed under Gaps with its Fix, and never lowers READY by itself.

Design Completeness

• Requirement traced: the story names its design/gdd/ file and quotes or links a specific rule or criterion from it, not just the file name. At minimal: design/game-brief.md and the MVP feature the story implements. A named design document that does not exist: NOT ASSESSED.
• Self-contained: the acceptance criteria say what done means without opening the GDD.
• Testable: each criterion is a specific, observable condition. Not: "Implement the jump mechanic." Yes: "Jump reaches 5 units within 0.3 seconds when held." A criterion a unit test can set up (any input values) is testable, even when the shipped data never reaches that case.
• No judgement calls: "feels responsive" or "looks good" fails for Logic, Integration, UI and Config/Data. For Visual/Feel such criteria are expected: pass when the criterion names an evidence file such as production/qa/evidence/[slug]-evidence.md, NEEDS WORK when it names none.

Architecture Completeness

• ADR status, at every tier: each ADR the story cites, by the Phase 2 table.
  • Accepted: pass.
  • Proposed: BLOCKED. Fix: BLOCKED: ADR-NNNN is Proposed — accept it with /architecture-decision accept ADR-NNNN once decided.
  • Deprecated or Superseded: BLOCKED. Fix: BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field; /create-stories never rewrites an existing story).
  • No such ADR file: BLOCKED.
  • No readable status: NOT ASSESSED for this item; name the file. At standard, a critical ADR (its layer is Foundation, or missing) that is missing or Proposed blocks; for other ADRs the items below are advisory.
• ADR cited or N/A stated: an ADR, or an explicit N/A with a reason (ADR: N/A — [reason], or N/A (minimal — no ADRs)). Blank fails.
• TR-ID valid: each TR-[system]-NNN is in the registry with status: active. deprecated or superseded-by (quoted or not): NEEDS WORK, Fix: point the story at the current requirement. Not in the registry: NEEDS WORK (the story may predate it, or the registry needs /architecture-review). Passes with no TR-ID, or no registry.
• Manifest Version current: the story's Manifest Version against the manifest's. Older: a gap, because rules added since may apply. It stays a gap even when the new rules look unrelated: say what changed, and leave the call to the user. At full it is NEEDS WORK whatever the new rules cover; at standard it is advisory. Fix, all three steps: "Review the manifest rules added since [story's date]; update the story's rules if any apply; then set its Manifest Version to [current date]." Passes with no Manifest Version field, or no manifest.
• Engine notes: post-cutoff engine APIs the story touches have notes or a verification step, or the story states "N/A — no engine API involved".
• Manifest rules noted: the layer's rules are listed, or "N/A — manifest not yet created". Passes when there is no manifest.

Scope Clarity

• Estimate: hours, points or a t-shirt size. unfilled Estimate (still the template's bracket) fails. Advisory at minimal.
• Out of scope stated: an Out of Scope section, or wording that leaves the boundary unambiguous.
• Dependencies listed: each story this one needs, or "None" stated.

Open Questions

• No open markers: no marker rows (TBD, TODO or UNRESOLVED as whole words in capitals). A ? is not a marker: a formula like crit ? 2 : 1 passes. A criterion written as an open question still fails Testable.
• Dependencies exist and are not Draft: a dependency story that is missing or Draft makes the story BLOCKED. Story NNN means that number in the same epic folder; a path names one exactly.

Asset References

• Assets the story uses exist: paths under assets/, or with .png, .jpg, .svg, .wav, .ogg, .mp3, .glb, .gltf, .tres, .tscn or .res, that the story reads or builds on. A file the story says it will create (a new scene, a new data file) is not checked. Missing: NEEDS WORK; name the path. Report "Referenced assets verified: [N] found", or "No asset references". Existence only.

Definition of Done

• Enough acceptance criteria: no ac_below_min row. The minimums follow story_granularity, because /create-stories writes to it:

  story_granularity	Logic, Integration	Visual/Feel, UI	Config/Data
  coarse	3	2	1
  balanced	2	2	1
  fine	1	1	1

• Performance noted: a story touching the gameplay loop, rendering or physics states a budget, or "no performance impact expected — [reason]".

• Type declared: no type_missing or type_unknown row. Fix: add Type: [Logic|Integration|Visual/Feel|UI|Config/Data] to the header.

• Test evidence clear: a ## Test Evidence section saying where evidence goes: the test file for Logic and Integration; the retained screenshot of each screen under production/qa/evidence/ for UI; that plus production/qa/evidence/[story-slug]-evidence.md for Visual/Feel.

  • At qa.level: minimal, Logic, Integration and Config/Data pass: tests are waived. List no gap, and add no note, about a missing test file, tests/ folder or test runner. UI and Visual/Feel are still checked: their screenshot is required at every level.
  • Otherwise the gate_level line above sets the level for the story's type. blocking: a missing section is NEEDS WORK. advisory: a listed gap only. Fix: add ## Test Evidence with the evidence location for the story's type.

Phase 4: Verdict

Apply the order at the top to each story. A BLOCKED story may also have NEEDS WORK items: list both.

Phase 5: QA lead review

Read the review_gate line above. skill-gates=skip (solo or lean): skip it, and the reply says "QL-STORY-READY skipped — [Solo | Lean] mode". skill-gates=run: read references/qa-lead-gate.md and .claude/docs/director-gates.md, and run it before reporting. On a skip, do not load it.

Phase 6: Report and close

One story:

## Story Readiness: [story title]
File: [path]
Verdict: [READY / NEEDS WORK / BLOCKED / NOT ASSESSED]

### Passing Checks (N/[total])
Design Completeness: [passing items]
Architecture Completeness: [passing items, or "N/A at minimal (ADR status checked)"]
Scope Clarity: [passing items]
Open Questions: [passing items]
Asset References: [passing items, or "no asset references"]
Definition of Done: [passing items]

### Gaps
- [Checklist item]: [what is missing or wrong]
  Fix: [the text that resolves it]

### Blockers (if BLOCKED)
- [What blocks]: [the story, ADR or question that must clear first]

Name all six groups every time, by these exact names. A group with nothing passing says "none — see Gaps", so the reader sees it was checked.

Gaps lists failed checklist items only: never a passing or N/A item, and never an observation from outside the checklist (a sprint status, another document).

Several stories: a summary first, then the one-story block for each story that is not READY.

## Story Readiness Summary — [scope] — [date]
Ready: [N] · Needs Work: [N] · Blocked: [N] · Not Assessed: [N]

Ready: [title] ([path]), ...
Needs Work: [title]: [main gap]
Blocked: [title]: blocked by [story, ADR or question]
Not Assessed: [title]: [what could not be read]

sprint scope: when a Must Have story is not READY, put this first: WARNING: [N] Must Have stories are not ready to implement: [each with its main gap]. Fix them before the sprint starts, or replan with /sprint-plan update.

Then, for one story: look for other stories to start. In the newest plan in production/sprints/, find up to 3 that are Ready or Not Started, not this one, not waiting on unfinished dependencies, and Must Have or Should Have. List each with a one-line description and its estimate. When there are none, say which: Next ready stories: no sprint file found or Next ready stories: none ready in [sprint].

Offer help. Ask: "Would you like me to draft the missing parts for any of these stories?" Options: Yes, draft them / No, that's all. On yes, draft only the missing parts, in the conversation. The user, or /create-stories, writes them.

Redirects:

• Story file missing: run /create-stories [epic-slug] (at standard and full, /create-epics first).
• No design reference and the change is small (under about a week): run /quick-design [description] and cite that spec in the story.
• Scope grew past its sizing: split the story, or raise it with the producer.

End the reply with:

Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdict]
Next ready stories: [up to 3 | no sprint file found | none ready in [sprint]]   (one-story scope)
Next step: [/dev-story [path] when READY | fix the gaps above, then /story-readiness [path]]
Files changed: none