story-readiness

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 .agents/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