story-readiness skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,qa.level,testing.strict,system_overrides

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

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 / NOT ASSESSED) with a specific

NOT ASSESSED is not a synonym for BLOCKED. BLOCKED is a

finding about the story — a Proposed ADR, an unresolved dependency — and it

tells the reader exactly what to clear. Use NOT ASSESSED when the story could

not be evaluated at all: the file is unreadable or unparseable, or a referenced

ADR or design document cannot be located, so the checks below cannot run.

Collapsing that into BLOCKED reports a blocker that does not exist and hides

the one that does — the reader chases a phantom ADR instead of a missing file.

READY must never be reachable for a story that was not actually evaluated.

Precedence — first matching rule wins, in this order: BLOCKED, then

NEEDS WORK, then NOT ASSESSED, then READY. NOT ASSESSED outranks

READY (a story that could not be evaluated has not been shown ready) and

ranks below both failure verdicts (a known blocker is more actionable than

an unknown, and demoting it behind an access problem buries it). A story with

both a real blocker and an unevaluable check is BLOCKED — the blocker is the

actionable finding. This half of the rank has to be stated: the rule above

establishes only that READY is unreachable, which would leave the ordering

against BLOCKED to inference.

gap list for each non-ready story.

Phase 0: Resolve Review Mode

See .claude/docs/director-gates.md for the full check pattern and mode definitions. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Resolve the workflow tier per story (per .claude/docs/workflow-modes.md): for the system a story belongs to (the GDD filename stem of its GDD: path; the [system] segment of a TR-[system]-NNN ID is a fallback alias only), use the systemoverrides row for that system if the block lists one, else the project value. When validating multiple stories (all / sprint scope), resolve per story** — different systems may sit at different tiers. The tier sets which checklist sections block — see the note in Section 3.

qa.level: controls whether a test requirement is validated. At minimal, the "Test evidence requirement is clear" item auto-passes (no requirement validated); at standard, validate the per-type test requirement (strictness from testing.strict); at full, also validate a coverage target. Distinct axis from workflow.

1. Parse Arguments

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

validate that single story file.

• Specific path (e.g., /story-readiness production/epics/combat/story-001-basic-attack.md):

recent file), extract every story path it references, validate each one.

• sprint: read the current sprint plan from production/sprints/ (most

validate every story file found.

• all: glob production/epics//.md, exclude EPIC.md index files,

• No argument: ask the user which scope to validate.

If no argument is given, use AskUserQuestion:

"All stories in production/epics/", "Stories for a specific epic"

• "What would you like to validate?"
• Options: "A specific story file", "All stories in the current sprint",

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

**If the scope resolves to ZERO story files, stop and report

NOT ASSESSED — no stories in scope.** Name which scope was searched and

which path was empty (production/epics//.md, the sprint file's story

list, or the specific path given), and route: /create-epics [layer] then

/create-stories [epic-slug].

The zero-scope path is mandatory. Without it an empty glob falls through

to the Section 5 aggregate template and renders Ready: 0 /

Needs Work: 0 / Blocked: 0 above an empty list — **indistinguishable from

"I checked every story and none needed work"**. It is the core failure of this

framework exactly: a scan that finds nothing because there was nothing to

scan, reported the same way as a clean result. Three zeros read as a healthy

sprint.

Note what made this survive: NOT ASSESSED was already in this skill's

vocabulary, but the body scoped it to per-story evaluation failures (an

unreadable or unparseable file, a missing referenced ADR). The verdict existed;

the case that most needs it had no route to it. It is a recurring shape — a

correct fix that did not reach one surface.

A zero-story sprint scope is not the same as an absent sprint file. If