349 lines
15 KiB
Markdown
349 lines
15 KiB
Markdown
---
|
|
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: haiku
|
|
---
|
|
|
|
# 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**: Criteria like
|
|
"feels responsive" or "looks good" are not testable without a defined
|
|
benchmark. These must be replaced with specific observable conditions or
|
|
playtest protocols.
|
|
|
|
### 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, look it up in the TR registry loaded in Section 2.
|
|
- If the ID exists and `status: active` → pass.
|
|
- If the ID exists and `status: deprecated` or `status: superseded-by: ...` →
|
|
NEEDS WORK: the requirement was removed or replaced.
|
|
Fix: update the story to reference the current requirement ID or remove if no longer applicable.
|
|
- If the ID does not exist in the registry → NEEDS WORK: ID was not registered
|
|
(story may predate registry, or registry needs an `/architecture-review` run).
|
|
- Auto-pass if the story has no TR-ID reference OR if the registry does not exist.
|
|
- [ ] **Manifest version is current**: If the story has a `Manifest Version:` date
|
|
in its header AND `docs/architecture/control-manifest.md` exists:
|
|
- If story version matches current manifest `Manifest Version:` → pass.
|
|
- If story version is older than current manifest → NEEDS WORK: new rules may
|
|
apply. Fix: review changed manifest rules, update story if any forbidden/required
|
|
entries changed, then update the story's `Manifest Version:` to current.
|
|
- Auto-pass if either the story has no `Manifest Version:` field OR the manifest
|
|
does not exist.
|
|
- [ ] **Engine notes present**: For any post-cutoff engine API this story
|
|
is likely to touch, implementation notes or a verification requirement are
|
|
included. If the story clearly does not touch engine APIs (e.g., it is a
|
|
pure data/config change), "N/A — no engine API involved" is acceptable.
|
|
- [ ] **Control manifest rules noted**: Relevant layer rules from the control
|
|
manifest are referenced, OR "N/A — manifest not yet created" is stated.
|
|
This item auto-passes if `docs/architecture/control-manifest.md` does not
|
|
exist yet (do not penalize stories written before the manifest was created).
|
|
|
|
### Scope Clarity
|
|
|
|
- [ ] **Estimate present**: The story includes a size estimate (hours,
|
|
points, or a t-shirt size). A story with no estimate cannot be planned.
|
|
- [ ] **In-scope / Out-of-scope boundary stated**: The story states what
|
|
it does NOT include, either in an explicit Out of Scope section or in
|
|
language that makes the boundary unambiguous. Without this, scope creep
|
|
during implementation is likely.
|
|
- [ ] **Story dependencies listed**: If this story depends on other stories
|
|
being DONE first, those story IDs are listed. If there are no dependencies,
|
|
"None" is explicitly stated (not just omitted).
|
|
|
|
### Open Questions
|
|
|
|
- [ ] **No unresolved design questions**: The story does not contain text
|
|
flagged as "UNRESOLVED", "TBD", "TODO", "?", or equivalent markers in
|
|
any acceptance criterion, implementation note, or rule statement.
|
|
- [ ] **Dependency stories are not in DRAFT**: For each story listed as a
|
|
dependency, check if the file exists and does not have a DRAFT status. A
|
|
story that depends on a DRAFT or missing story is BLOCKED, not just
|
|
NEEDS WORK.
|
|
|
|
### Asset References Check
|
|
|
|
- [ ] **Referenced assets exist**: Scan the story text for asset path patterns
|
|
(paths containing `assets/`, or file extensions `.png`, `.jpg`, `.svg`,
|
|
`.wav`, `.ogg`, `.mp3`, `.glb`, `.gltf`, `.tres`, `.tscn`, `.res`).
|
|
- For each asset path found: use Glob to check whether the file exists.
|
|
- If any referenced asset does not exist: **NEEDS WORK** — note the missing
|
|
path(s). (The story references assets that have not been created yet.
|
|
Either remove the reference, create a placeholder, or mark it as an
|
|
explicit dependency on an asset creation story.)
|
|
- If all referenced assets exist: note "Referenced assets verified:
|
|
[count] found."
|
|
- If no asset paths are referenced in the story: note "No asset references
|
|
found in story — skipping asset check." This item auto-passes.
|
|
- This is an existence-only check. Do not validate file format or content.
|
|
|
|
### Definition of Done
|
|
|
|
- [ ] **At least 3 testable acceptance criteria**: Fewer than 3 suggests
|
|
the story is either trivially small (should it be a story?) or under-specified.
|
|
- [ ] **Performance budget noted if applicable**: If this story touches any
|
|
part of the gameplay loop, rendering, or physics, a performance budget or
|
|
a "no performance impact expected — [reason]" note is present.
|
|
- [ ] **Story Type declared**: The story includes a `Type:` field in its header
|
|
identifying the test category (Logic / Integration / Visual/Feel / UI / Config/Data).
|
|
Without this, test evidence requirements cannot be enforced at story close.
|
|
Fix: Add `Type: [Logic|Integration|Visual/Feel|UI|Config/Data]` to the story header.
|
|
- [ ] **Test evidence requirement is clear**: If the Story Type is set, the story
|
|
includes a `## Test Evidence` section stating where evidence will be stored
|
|
(test file path for Logic/Integration, or evidence doc path for Visual/Feel/UI).
|
|
Fix: Add `## Test Evidence` with the expected evidence location for the story's type.
|
|
|
|
---
|
|
|
|
## 4. Verdict Assignment
|
|
|
|
Assign one of three verdicts per story:
|
|
|
|
**READY** — All checklist items pass or have explicit N/A justifications.
|
|
The story can be assigned immediately.
|
|
|
|
**NEEDS WORK** — One or more checklist items fail, but all dependency stories
|
|
exist and are not DRAFT. The story can be fixed before assignment.
|
|
|
|
**BLOCKED** — One or more dependency stories are missing or in DRAFT state,
|
|
OR a critical design question (flagged UNRESOLVED in a criterion or rule) has
|
|
no owner. The story cannot be assigned until the blocker is resolved. Note:
|
|
a story that is BLOCKED may also have NEEDS WORK items — list both.
|
|
|
|
---
|
|
|
|
## 5. Output Format
|
|
|
|
### Single story output
|
|
|
|
```
|
|
## Story Readiness: [story title]
|
|
File: [path]
|
|
Verdict: [READY / NEEDS WORK / BLOCKED]
|
|
|
|
### Passing Checks (N/[total])
|
|
[list passing items briefly]
|
|
|
|
### Gaps
|
|
- [Checklist item]: [exact description of what is missing or wrong]
|
|
Fix: [specific text needed to resolve this gap]
|
|
|
|
### Blockers (if BLOCKED)
|
|
- [What is blocking]: [story ID or design question that must resolve first]
|
|
```
|
|
|
|
### Multiple story aggregate output
|
|
|
|
```
|
|
## Story Readiness Summary — [scope] — [date]
|
|
|
|
Ready: [N] stories
|
|
Needs Work: [N] stories
|
|
Blocked: [N] stories
|
|
|
|
### Ready Stories
|
|
- [story title] ([path])
|
|
|
|
### Needs Work
|
|
- [story title]: [primary gap — one line]
|
|
- [story title]: [primary gap — one line]
|
|
|
|
### Blocked Stories
|
|
- [story title]: Blocked by [story ID / design question]
|
|
|
|
---
|
|
[Full detail for each non-ready story follows, using the single-story format]
|
|
```
|
|
|
|
### Sprint escalation
|
|
|
|
If the scope is `sprint` and any Must Have stories are NEEDS WORK or BLOCKED,
|
|
add a prominent warning at the top of the output:
|
|
|
|
```
|
|
WARNING: [N] Must Have stories are not implementation-ready.
|
|
[List them with their primary gap or blocker.]
|
|
Resolve these before the sprint begins or replan with `/sprint-plan update`.
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Collaborative Protocol
|
|
|
|
This skill is read-only. It never proposes edits or asks to write files.
|
|
|
|
After reporting findings, offer:
|
|
|
|
"Would you like help filling in the gaps for any of these stories? I can
|
|
draft the missing sections for your approval."
|
|
|
|
If the user says yes for a specific story, draft only the missing sections
|
|
in conversation. Do not use Write or Edit tools — the user (or
|
|
`/create-stories`) handles writing.
|
|
|
|
**Redirect rules:**
|
|
- If a story file does not exist at all: "This story file is missing entirely.
|
|
Run `/create-epics [layer]` then `/create-stories [epic-slug]` to generate stories from the GDD and ADR."
|
|
- If a story has no GDD reference and the work appears small: "This story has
|
|
no GDD reference. If the change is small (under ~4 hours), run
|
|
`/quick-design [description]` to create a Quick Design Spec, then reference
|
|
that spec in the story."
|
|
- If a story's scope has grown beyond its original sizing: "This story appears
|
|
to have expanded in scope. Consider splitting it or escalating to the producer
|
|
before implementation begins."
|
|
|
|
---
|
|
|
|
## 7. Next-Story Handoff
|
|
|
|
After completing a single-story readiness check (not `all` or `sprint` scope):
|
|
|
|
1. Read the current sprint file from `production/sprints/` (most recent).
|
|
2. Find stories that are:
|
|
- Status: READY or NOT STARTED
|
|
- Not the story just checked
|
|
- Not blocked by incomplete dependencies
|
|
- In the Must Have or Should Have tier
|
|
|
|
If any are found, surface up to 3:
|
|
|
|
```
|
|
### Other Ready Stories in This Sprint
|
|
|
|
1. [Story name] — [1-line description] — Est: [X hrs]
|
|
2. [Story name] — [1-line description] — Est: [X hrs]
|
|
|
|
Run `/story-readiness [path]` to validate before starting.
|
|
```
|
|
|
|
If no sprint file exists or no other ready stories are found, skip this section silently.
|
|
|
|
---
|
|
|
|
## Phase 8: Director Gate — Story Readiness Review
|
|
|
|
Apply the review mode resolved in Phase 0 before spawning QL-STORY-READY:
|
|
|
|
- `solo` → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to close.
|
|
- `lean` → skip. Note: "QL-STORY-READY skipped — Lean mode." Proceed to close.
|
|
- `full` → spawn as normal.
|
|
|
|
Spawn `qa-lead` via Task using gate **QL-STORY-READY** (`.claude/docs/director-gates.md`).
|
|
|
|
Pass the following context:
|
|
- Story title
|
|
- Acceptance criteria list (all items from the story's acceptance criteria section)
|
|
- Dependency status (all dependencies listed and their current state: exist / DRAFT / missing)
|
|
- Overall verdict (READY / NEEDS WORK / BLOCKED) from Phase 4
|
|
|
|
Handle the verdict per standard rules in `director-gates.md`:
|
|
- **ADEQUATE** → story is cleared. Proceed to close.
|
|
- **GAPS [list]** → surface the specific gaps to the user via `AskUserQuestion`:
|
|
options: `Update story with suggested gaps` / `Accept and proceed anyway` / `Discuss further`.
|
|
- **INADEQUATE** → surface the specific gaps; ask user whether to update the story or proceed anyway.
|
|
|
|
---
|
|
|
|
## Recommended Next Steps
|
|
|
|
- Run `/dev-story [story-path]` to begin implementation once the story is READY
|
|
- Run `/story-readiness sprint` to check all stories in the current sprint at once
|
|
- Run `/create-stories [epic-slug]` if a story file is missing entirely
|