mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-28 05:31:46 +00:00
Add v0.6.0: full skill/agent QA pass, 3 new agents tested, template cleanup
Skills fixed: sprint-status (stale escalation, threshold), retrospective (existing file detection, missing data fallback), changelog (misc category, task-ref count), patch-notes (BLOCKED on missing changelog, tone/template paths), story-readiness (Phase 0 mode resolution, QL-STORY-READY gate), art-bible, brainstorm, design-system, ux-design, dev-story, story-done, create-architecture, create-control-manifest, map-systems, propagate-design-change, quick-design, prototype, asset-spec. Agents fixed: all 4 directors (gate verdict token format), engine-programmer, ui-programmer, tools-programmer, technical-artist (engine version safety), gameplay-programmer (ADR compliance), godot-gdextension-specialist (ABI warning), systems-designer (escalation path to creative-director), accessibility-specialist (model, tools, WCAG criterion format, findings template), live-ops-designer (escalation paths, battle pass value language), qa-tester (model, test case format, evidence routing, ambiguous criteria, regression scope). Specs updated: smoke-check and adopt specs rewritten to match actual skill behavior. catalog.yaml reset to blank template state. Removed session-state marketing research file, removed session-state from gitignore. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
@@ -25,7 +25,30 @@ Extract from game-concept.md:
|
||||
- **Visual Identity Anchor** section if present (from brainstorm Phase 4 art-director output)
|
||||
- Target platform (if noted)
|
||||
|
||||
Read `design/art/art-bible.md` if it exists — this is **resume mode**. Read which sections already have real content vs. placeholders. Only work on missing sections.
|
||||
**Retrofit mode detection**: Glob `design/art/art-bible.md`. If the file exists:
|
||||
- Read it in full
|
||||
- For each of the 9 sections, check whether the body contains real content (more than a `[To be designed]` placeholder or similar) vs. is empty/placeholder
|
||||
- Build a section status table:
|
||||
|
||||
```
|
||||
Section | Status
|
||||
--------|--------
|
||||
1. Visual Identity Statement | [Complete / Empty / Placeholder]
|
||||
2. Color Palette | ...
|
||||
3. Lighting & Atmosphere | ...
|
||||
4. Character Art Direction | ...
|
||||
5. Environment & Level Art | ...
|
||||
6. UI Visual Language | ...
|
||||
7. VFX & Particle Style | ...
|
||||
8. Asset Standards | ...
|
||||
9. Style Prohibitions | ...
|
||||
```
|
||||
|
||||
- Present this table to the user:
|
||||
> "Found existing art bible at `design/art/art-bible.md`. [N] sections are complete, [M] need content. I'll work on the incomplete sections only — existing content will not be touched."
|
||||
- Only work on sections with Status: Empty or Placeholder. Do not re-author sections that are already complete.
|
||||
|
||||
If the file does not exist, this is a fresh authoring session — proceed normally.
|
||||
|
||||
Read `.claude/docs/technical-preferences.md` if it exists — extract performance budgets and engine for asset standard constraints.
|
||||
|
||||
@@ -212,3 +235,14 @@ Every section follows: **Question → Options → Decision → Draft (from art-d
|
||||
- Write each section to file immediately after approval — do not batch
|
||||
- Surface all agent disagreements to the user — never silently resolve conflicts between art-director and technical-artist
|
||||
- The art bible is a constraint document: it restricts future decisions in exchange for visual coherence. Every section should feel like it narrows the solution space productively.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
After the art bible is approved:
|
||||
- Run `/map-systems` to decompose the concept into game systems before authoring GDDs
|
||||
- Run `/setup-engine` if the engine is not yet configured (asset standards may need revisiting after engine selection)
|
||||
- Run `/design-system [first-system]` to start authoring per-system GDDs
|
||||
- Run `/consistency-check` once GDDs exist to validate them against the art bible's visual rules
|
||||
- Run `/create-architecture` to produce the master architecture document
|
||||
|
||||
@@ -255,3 +255,10 @@ Every phase follows: **Identify → Confirm → Generate → Review → Approve
|
||||
- Surface all agent disagreements — do not silently pick one
|
||||
- Write the spec file only after explicit approval
|
||||
- Update the manifest immediately after writing the spec
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/asset-spec [next-context]` to continue speccing remaining systems, levels, or characters
|
||||
- Run `/asset-audit` to validate delivered assets against the written specs and identify gaps or mismatches
|
||||
|
||||
@@ -336,3 +336,15 @@ append this notice to the current response before continuing:
|
||||
> **Context is approaching the limit (≥70%).** The game concept document is saved
|
||||
> to `design/gdd/game-concept.md`. Open a fresh Claude Code session to continue
|
||||
> if needed — progress is not lost.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
After the game concept is written, follow the pre-production pipeline in order:
|
||||
1. `/setup-engine` — configure the engine and populate version-aware reference docs
|
||||
2. `/art-bible` — establish visual identity before writing any GDDs
|
||||
3. `/map-systems` — decompose the concept into individual systems with dependencies
|
||||
4. `/design-system [first-system]` — author per-system GDDs in dependency order
|
||||
5. `/create-architecture` — produce the master architecture blueprint
|
||||
6. `/gate-check pre-production` — validate readiness before committing to production
|
||||
|
||||
@@ -3,7 +3,7 @@ name: changelog
|
||||
description: "Auto-generates a changelog from git commits, sprint data, and design documents. Produces both internal and player-facing versions."
|
||||
argument-hint: "[version|sprint-number]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
allowed-tools: Read, Glob, Grep, Bash, Write
|
||||
context: |
|
||||
!git log --oneline -30 2>/dev/null
|
||||
!git tag --list --sort=-v:refname 2>/dev/null | head -5
|
||||
@@ -43,6 +43,11 @@ Categorize every change into one of these categories:
|
||||
- **Bug Fixes**: Corrections to broken behavior
|
||||
- **Balance Changes**: Tuning of gameplay values, difficulty, economy
|
||||
- **Known Issues**: Issues the team is aware of but have not yet resolved
|
||||
- **Miscellaneous**: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently
|
||||
|
||||
For each commit, check whether the message contains a task ID or story reference
|
||||
(e.g. `[STORY-123]`, `TR-`, `#NNN`, or similar). Count commits that lack any task reference
|
||||
and include this count in the Phase 4 Metrics section as: `Commits without task reference: [N]`.
|
||||
|
||||
---
|
||||
|
||||
@@ -79,6 +84,10 @@ Commits: [Count] ([first-hash]..[last-hash])
|
||||
- [What was cleaned up and why]
|
||||
- Commits: [hashes]
|
||||
|
||||
## Miscellaneous
|
||||
- [Change that didn't fit other categories, or vague commit message]
|
||||
- Commits: [hashes]
|
||||
|
||||
## Known Issues
|
||||
- [Issue description] -- [Severity] -- [ETA for fix if known]
|
||||
|
||||
@@ -87,6 +96,7 @@ Commits: [Count] ([first-hash]..[last-hash])
|
||||
- Files changed: [N]
|
||||
- Lines added: [N]
|
||||
- Lines removed: [N]
|
||||
- Commits without task reference: [N]
|
||||
```
|
||||
|
||||
---
|
||||
@@ -129,9 +139,26 @@ Report issues at [link].
|
||||
|
||||
Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.
|
||||
|
||||
This skill is read-only — it outputs to conversation but does not write files. To save the output, copy it manually or use `/patch-notes` which includes a save step.
|
||||
---
|
||||
|
||||
Verdict: **COMPLETE** — changelog generated.
|
||||
## Phase 7: Offer File Write
|
||||
|
||||
After presenting the changelogs, ask the user:
|
||||
|
||||
> "May I write this changelog to `docs/CHANGELOG.md`?
|
||||
> [A] Yes, append this entry (recommended if the file already exists)
|
||||
> [B] Yes, overwrite the file entirely
|
||||
> [C] No — I'll copy it manually"
|
||||
|
||||
- Check whether `docs/CHANGELOG.md` exists before asking. If it does, default the
|
||||
recommendation to **[A] append**.
|
||||
- If the user selects [A]: append the new internal changelog entry to the top of
|
||||
the existing file (newest entries first).
|
||||
- If the user selects [B]: overwrite the file with the new changelog.
|
||||
- If the user selects [C]: stop here without writing.
|
||||
|
||||
After a successful write: Verdict: **CHANGELOG WRITTEN** — changelog saved to `docs/CHANGELOG.md`.
|
||||
If the user declines: Verdict: **COMPLETE** — changelog generated.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -392,3 +392,11 @@ This skill follows the collaborative design principle at every phase:
|
||||
|
||||
Never make a binding architectural decision without user input. If the user is
|
||||
unsure, present 2-4 options with pros/cons before asking them to decide.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/architecture-decision [title]` for each required ADR listed in Phase 6 — Foundation layer ADRs first
|
||||
- Run `/create-control-manifest` once the required ADRs are written to produce the layer rules manifest
|
||||
- Run `/gate-check pre-production` when all required ADRs are written and the architecture is signed off
|
||||
|
||||
@@ -3,7 +3,7 @@ name: create-control-manifest
|
||||
description: "After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why)."
|
||||
argument-hint: "[update — regenerate from current ADRs]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write
|
||||
allowed-tools: Read, Glob, Grep, Write, Task
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
@@ -116,6 +116,30 @@ Ask: "Does this look complete? Any rules to add or remove before I write the man
|
||||
|
||||
---
|
||||
|
||||
## 4b. Director Gate — Technical Review
|
||||
|
||||
**Review mode check** — apply before spawning TD-MANIFEST:
|
||||
- `solo` → skip. Note: "TD-MANIFEST skipped — Solo mode." Proceed to Phase 5.
|
||||
- `lean` → skip. Note: "TD-MANIFEST skipped — Lean mode." Proceed to Phase 5.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `technical-director` via Task using gate **TD-MANIFEST** (`.claude/docs/director-gates.md`).
|
||||
|
||||
Pass: the Control Manifest Preview from Phase 4 (rule counts per layer, full extracted rule list), the list of ADRs covered, engine version, and any rules sourced from technical-preferences.md or engine reference docs.
|
||||
|
||||
The technical-director reviews whether:
|
||||
- All mandatory ADR patterns are captured and accurately stated
|
||||
- Forbidden approaches are complete and correctly attributed
|
||||
- No rules were added that lack a source ADR or preference document
|
||||
- Performance guardrails are consistent with the ADR constraints
|
||||
|
||||
Apply the verdict:
|
||||
- **APPROVE** → proceed to Phase 5
|
||||
- **CONCERNS** → surface via `AskUserQuestion` with options: `Revise flagged rules` / `Accept and proceed` / `Discuss further`
|
||||
- **REJECT** → do not write the manifest; fix the flagged rules and re-present the summary
|
||||
|
||||
---
|
||||
|
||||
## 5. Write the Control Manifest
|
||||
|
||||
Ask: "May I write this to `docs/architecture/control-manifest.md`?"
|
||||
|
||||
@@ -830,3 +830,12 @@ shows context at or above 70%. If so, append this notice to the response:
|
||||
> sections are written to `design/gdd/[system-name].md`. When you're ready to continue,
|
||||
> open a fresh Claude Code session and run `/design-system [system-name]` — it will
|
||||
> detect which sections are complete and resume from the next one.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/design-review design/gdd/[system-name].md` in a **fresh session** to validate the completed GDD independently
|
||||
- Run `/consistency-check` to verify this GDD's values don't conflict with other GDDs
|
||||
- Run `/map-systems next` to move to the next highest-priority undesigned system
|
||||
- Run `/gate-check pre-production` when all MVP GDDs are authored and reviewed
|
||||
|
||||
@@ -94,6 +94,27 @@ If [A]: edit the story file's `Manifest Version:` field to the current manifest
|
||||
If [B]: read the manifest carefully for new rules anyway, and note the version mismatch in the Phase 6 summary under "Deviations".
|
||||
If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`.
|
||||
|
||||
### Dependency validation
|
||||
|
||||
After extracting the **Dependencies** list from the story file, validate each:
|
||||
|
||||
1. Glob `production/epics/**/*.md` to find each dependency story file.
|
||||
2. Read its `Status:` field.
|
||||
3. If any dependency has Status other than `Complete` or `Done`:
|
||||
- Use `AskUserQuestion`:
|
||||
- Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
|
||||
- Options:
|
||||
- `[A] Proceed anyway — I accept the dependency risk`
|
||||
- `[B] Stop — I'll complete the dependency first`
|
||||
- `[C] The dependency is done but status wasn't updated — mark it Complete and continue`
|
||||
- If [B]: set story status to **BLOCKED** in session state and stop. Do not spawn any programmer agent.
|
||||
- If [C]: ask "May I update [dependency path] Status to Complete?" before continuing.
|
||||
- If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."
|
||||
|
||||
If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."
|
||||
|
||||
---
|
||||
|
||||
### Engine reference
|
||||
Read `.claude/docs/technical-preferences.md`:
|
||||
- `Engine:` value — determines which programmer agents to use
|
||||
@@ -292,3 +313,11 @@ Common blockers:
|
||||
- **Ask before large structural decisions** — if the story requires an
|
||||
architectural pattern not covered by the ADR, surface it before implementing:
|
||||
"The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?"
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/code-review [file1] [file2]` to review the implementation before closing the story
|
||||
- Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete
|
||||
- After all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage
|
||||
|
||||
@@ -352,3 +352,12 @@ If context reaches or exceeds 70% at any point, append this notice:
|
||||
> **Context is approaching the limit (≥70%).** The systems index is saved to
|
||||
> `design/gdd/systems-index.md`. Open a fresh Claude Code session to continue
|
||||
> designing individual GDDs — run `/map-systems next` to pick up where you left off.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/design-system [first-system-in-order]` to author the first GDD (use design order from the index)
|
||||
- Run `/map-systems next` to always pick the highest-priority undesigned system automatically
|
||||
- Run `/design-review design/gdd/[system].md` in a fresh session after each GDD is authored
|
||||
- Run `/gate-check pre-production` when all MVP GDDs are authored and reviewed
|
||||
|
||||
@@ -20,11 +20,44 @@ If no version is provided, ask the user before proceeding.
|
||||
## Phase 2: Gather Change Data
|
||||
|
||||
- Read the internal changelog at `production/releases/[version]/changelog.md` if it exists
|
||||
- Run `git log` between the previous release tag and current tag/HEAD
|
||||
- Also check `docs/CHANGELOG.md` for the relevant version entry
|
||||
- Run `git log` between the previous release tag and current tag/HEAD as a fallback
|
||||
- Read sprint retrospectives in `production/sprints/` for context
|
||||
- Read any balance change documents in `design/balance/`
|
||||
- Read bug fix records from QA if available
|
||||
|
||||
**If no changelog data is available** (neither `production/releases/[version]/changelog.md`
|
||||
nor a `docs/CHANGELOG.md` entry for this version exists, and git log is empty or unavailable):
|
||||
|
||||
> "No changelog data found for [version]. Run `/changelog [version]` first to generate the
|
||||
> internal changelog, then re-run `/patch-notes [version]`."
|
||||
|
||||
Verdict: **BLOCKED** — stop here without generating notes.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2b: Detect Tone Guide and Template
|
||||
|
||||
**Tone guide detection** — before drafting notes, check for writing style guidance:
|
||||
|
||||
1. Check `.claude/docs/technical-preferences.md` for any "tone", "voice", or "style"
|
||||
fields or sections.
|
||||
2. Check `docs/PATCH-NOTES-STYLE.md` if it exists.
|
||||
3. Check `design/community/tone-guide.md` if it exists.
|
||||
4. If any source contains tone/voice/style instructions, extract them and apply
|
||||
them to the language and framing of the generated notes.
|
||||
5. If no tone guidance is found anywhere, default to:
|
||||
player-friendly, non-technical language; enthusiastic but not hyperbolic;
|
||||
focus on what the player experiences, not what the developer changed.
|
||||
|
||||
**Template detection** — check whether a patch notes template exists:
|
||||
|
||||
1. Glob for `docs/patch-notes-template.md` and `.claude/docs/templates/patch-notes-template.md`.
|
||||
2. If found at either location, read it and use it as the output structure for Phase 4
|
||||
instead of the built-in style templates (Brief / Detailed / Full). Fill in the
|
||||
template's sections with the categorized data.
|
||||
3. If not found, use the built-in style templates as defined in Phase 4.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Categorize and Translate
|
||||
@@ -137,9 +170,11 @@ Check the generated notes for:
|
||||
|
||||
Present the completed patch notes to the user along with: a count of changes by category, and any internal changes that were excluded (for review).
|
||||
|
||||
Ask: "May I write this to `production/releases/[version]/patch-notes.md`?"
|
||||
Ask: "May I write these patch notes to `docs/patch-notes/[version].md`?"
|
||||
|
||||
If yes, write the file, creating the directory if needed.
|
||||
If yes, write the file to `docs/patch-notes/[version].md`, creating the directory
|
||||
if needed. Also write to `production/releases/[version]/patch-notes.md` as the
|
||||
internal archive copy.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ name: propagate-design-change
|
||||
description: "When a GDD is revised, scans all ADRs and the traceability index to identify which architectural decisions are now potentially stale. Produces a change impact report and guides the user through resolution."
|
||||
argument-hint: "[path/to/changed-gdd.md]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash, Task
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
@@ -145,6 +145,29 @@ ADRs referencing this GDD: [M]
|
||||
|
||||
---
|
||||
|
||||
## 6b. Director Gate — Technical Impact Review
|
||||
|
||||
**Review mode check** — apply before spawning TD-CHANGE-IMPACT:
|
||||
- `solo` → skip. Note: "TD-CHANGE-IMPACT skipped — Solo mode." Proceed to Phase 7.
|
||||
- `lean` → skip. Note: "TD-CHANGE-IMPACT skipped — Lean mode." Proceed to Phase 7.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `technical-director` via Task using gate **TD-CHANGE-IMPACT** (`.claude/docs/director-gates.md`).
|
||||
|
||||
Pass: the full Design Change Impact Report from Phase 6 (change summary, all affected ADRs with their Still Valid / Needs Review / Likely Superseded classifications, and recommended actions).
|
||||
|
||||
The technical-director reviews whether:
|
||||
- The impact classifications are correct (no ADRs under-classified)
|
||||
- The recommended actions are architecturally sound
|
||||
- Any cascading effects on other ADRs or systems were missed
|
||||
|
||||
Apply the verdict:
|
||||
- **APPROVE** → proceed to Phase 7 resolution workflow
|
||||
- **CONCERNS** → surface the specific ADRs or recommendations flagged; use `AskUserQuestion` with options: `Revise the impact assessment` / `Accept with noted concerns` / `Discuss further`
|
||||
- **REJECT** → do not proceed to resolution; re-analyze the impact before continuing
|
||||
|
||||
---
|
||||
|
||||
## 7. Resolution Workflow
|
||||
|
||||
For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:
|
||||
|
||||
@@ -146,3 +146,12 @@ Verdict: **COMPLETE** — prototype finished. Recommendation is PROCEED, PIVOT,
|
||||
- If the recommendation is PROCEED, the production implementation must be written from scratch — prototype code is not refactored into production
|
||||
- Total prototype effort should be timeboxed to 1-3 days equivalent of work
|
||||
- If the prototype scope starts growing, stop and reassess whether the question can be simplified
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- **If PROCEED**: Run `/design-system [mechanic]` to author the production GDD, or `/architecture-decision` to record key technical decisions before implementation
|
||||
- **If PIVOT**: Run `/prototype [revised-concept]` to test the adjusted direction
|
||||
- **If KILL**: No further action required — the prototype report is the deliverable
|
||||
- Run `/playtest-report` to formally document any playtest sessions conducted during prototyping
|
||||
|
||||
@@ -264,3 +264,11 @@ Redirect to the full pipeline if any of the following are true:
|
||||
|
||||
In those cases: "This change has grown beyond quick-spec scope. I recommend
|
||||
using `/design-system` to author a full GDD for this."
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/story-readiness [story-path]` to validate the story before implementation begins — reference this spec in the story's GDD Reference field
|
||||
- Run `/dev-story [story-path]` to implement once the story passes readiness checks
|
||||
- If the change is larger than expected, run `/design-system [system-name]` to author a full GDD instead
|
||||
|
||||
@@ -14,6 +14,28 @@ Determine whether this is a sprint retrospective (`sprint-N`) or a milestone ret
|
||||
|
||||
---
|
||||
|
||||
## Phase 1b: Check for Existing Retrospective
|
||||
|
||||
Before loading any data, glob for an existing retrospective file:
|
||||
|
||||
- For sprint retrospectives: `production/retrospectives/retro-[sprint-slug]-*.md`
|
||||
(also check `production/sprints/sprint-[N]-retrospective.md` as an alternate location)
|
||||
- For milestone retrospectives: `production/retrospectives/retro-[milestone-name]-*.md`
|
||||
|
||||
If a matching file is found, present the user with:
|
||||
|
||||
```
|
||||
An existing retrospective was found: [filename]
|
||||
|
||||
[A] Update existing retrospective — load it and add/revise sections
|
||||
[B] Start fresh — generate a new retrospective, archiving the old one
|
||||
```
|
||||
|
||||
Wait for user selection before continuing. If updating, read the existing file and
|
||||
carry its content forward into the generation phase, revising sections with new data.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Load Sprint or Milestone Data
|
||||
|
||||
Read the sprint or milestone plan from the appropriate location:
|
||||
@@ -21,6 +43,20 @@ Read the sprint or milestone plan from the appropriate location:
|
||||
- Sprint plans: `production/sprints/`
|
||||
- Milestone definitions: `production/milestones/`
|
||||
|
||||
**If the file does not exist or is empty**, output:
|
||||
|
||||
> "No sprint data found for [sprint/milestone]. Run `/sprint-status` to generate
|
||||
> sprint data first, or provide the sprint details manually."
|
||||
|
||||
Then use `AskUserQuestion` to present two options:
|
||||
|
||||
- **[A] Provide data manually** — ask the user to paste or describe the sprint
|
||||
tasks, dates, and outcomes; use that as the source of truth for the retrospective.
|
||||
- **[B] Stop** — abort the skill. Verdict: **BLOCKED** — no sprint data available.
|
||||
|
||||
If the user chooses [A], collect the data and continue to Phase 3 using what they provide.
|
||||
If the user chooses [B], stop here.
|
||||
|
||||
Extract: planned tasks, estimated effort, owners, and goals.
|
||||
|
||||
Read the git log for the period covered by the sprint or milestone to understand what was actually committed and when.
|
||||
|
||||
@@ -78,6 +78,27 @@ Optionally (fast check only — do not do a deep scan): grep `src/` for a
|
||||
directory or file name that matches the story's system slug to check for
|
||||
implementation evidence. This is a hint only, not a definitive status.
|
||||
|
||||
### Stale Story Detection
|
||||
|
||||
After collecting status for all stories, check each IN PROGRESS story for staleness:
|
||||
|
||||
- For each story that has a referenced file, read the file and look for a
|
||||
`Last Updated:` field in the frontmatter or header (e.g., `Last Updated: 2026-04-01`
|
||||
or `updated: 2026-04-01`). Accept any reasonable date field name: `Last Updated`,
|
||||
`Updated`, `last-updated`, `updated_at`.
|
||||
- Calculate days since that date using today's date.
|
||||
- If the date is more than 2 days ago, flag the story as **STALE**.
|
||||
- If no date field is found in the story file, note "no timestamp — cannot check staleness."
|
||||
- If the story has no referenced file (inline task), note "inline task — cannot check staleness."
|
||||
|
||||
STALE stories are included in the output table and collected into an "Attention Needed"
|
||||
section (see Phase 5 output format).
|
||||
|
||||
**Stale story escalation**: If any IN PROGRESS story is flagged STALE, the burndown verdict
|
||||
is upgraded to at least **At Risk** — even if the completion percentage is within the normal
|
||||
On Track window. Record this escalation reason: "At Risk — [N] story(ies) with no progress in
|
||||
[N] days."
|
||||
|
||||
---
|
||||
|
||||
## 4. Burndown Assessment
|
||||
@@ -118,6 +139,13 @@ Keep the total output to 30 lines or fewer. Use this format:
|
||||
| [title] | Must Have | BLOCKED | [owner] | [brief reason] |
|
||||
| [title] | Should Have| NOT STARTED | [owner] | |
|
||||
|
||||
### Attention Needed
|
||||
| Story / Task | Status | Last Updated | Days Stale | Note |
|
||||
|----------------------|-------------|----------------|------------|----------------|
|
||||
| [title] | IN PROGRESS | [date or N/A] | [N days] | [STALE / no timestamp — cannot check staleness / inline task — cannot check staleness] |
|
||||
|
||||
*(Omit this section entirely if no IN PROGRESS stories are stale or have timestamp concerns.)*
|
||||
|
||||
### Burndown: [On Track / At Risk / Behind]
|
||||
[1-2 sentences. If behind: which Must Haves are at risk. If on track: confirm
|
||||
and note any Should Haves the team could pull.]
|
||||
|
||||
@@ -418,3 +418,11 @@ If no more stories are ready but Must Have stories are still In Progress (not Co
|
||||
anyway; document the risk explicitly if they do.
|
||||
- Use `AskUserQuestion` for the code review prompt and for batching manual
|
||||
criteria confirmations.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/story-readiness [next-story-path]` to validate the next story before starting implementation
|
||||
- If all Must Have stories are complete: run `/smoke-check sprint` → `/team-qa sprint` → `/gate-check`
|
||||
- If tech debt was logged: track it via `/tech-debt` to keep the register current
|
||||
|
||||
@@ -3,7 +3,7 @@ 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
|
||||
allowed-tools: Read, Glob, Grep, AskUserQuestion, Task
|
||||
model: haiku
|
||||
---
|
||||
|
||||
@@ -21,6 +21,18 @@ 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)
|
||||
@@ -276,3 +288,61 @@ in conversation. Do not use Write or Edit tools — the user (or
|
||||
- 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
|
||||
|
||||
@@ -126,6 +126,41 @@ Then ask: "Anything else I should read before we start, or shall we proceed?"
|
||||
|
||||
---
|
||||
|
||||
## 2b. Retrofit Mode Detection
|
||||
|
||||
Before creating a skeleton, check if the target output file already exists.
|
||||
|
||||
Glob `design/ux/[filename].md` (where `[filename]` is the resolved output path from Phase 1).
|
||||
|
||||
**If the file exists — retrofit mode:**
|
||||
- Read the file in full
|
||||
- For each expected section, check whether the body has real content (more than a `[To be designed]` placeholder) or is empty/placeholder
|
||||
- Present a section status summary to the user:
|
||||
|
||||
> "Found existing UX spec at `design/ux/[filename].md`. Here's what's already done:
|
||||
>
|
||||
> | Section | Status |
|
||||
> |---------|--------|
|
||||
> | Overview & Context | [Complete / Empty / Placeholder] |
|
||||
> | Player Journey Integration | ... |
|
||||
> | Screen Layout & Information Architecture | ... |
|
||||
> | Interaction Model | ... |
|
||||
> | Feedback & State Communication | ... |
|
||||
> | Accessibility | ... |
|
||||
> | Edge Cases & Error States | ... |
|
||||
> | Open Questions | ... |
|
||||
>
|
||||
> I'll work on the [N] incomplete sections only — existing content will not be overwritten."
|
||||
|
||||
- Skip Section 3 (skeleton creation) — the file already exists
|
||||
- In Phase 4 (Section Authoring), only work on sections with Status: Empty or Placeholder
|
||||
- Use `Edit` to fill placeholders in-place rather than creating a new skeleton
|
||||
|
||||
**If the file does not exist — fresh authoring mode:**
|
||||
Proceed to Phase 3 (Create File Skeleton) as normal.
|
||||
|
||||
---
|
||||
|
||||
## 3. Create File Skeleton
|
||||
|
||||
Once the user confirms, **immediately** create the output file with empty section
|
||||
@@ -930,3 +965,11 @@ a requirement. Never silently expand the layout without flagging it.
|
||||
**Always** show where decisions come from (GDD requirements, player journey, user choices).
|
||||
|
||||
Verdict: **COMPLETE** — UX spec written and approved section by section.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/ux-review [filename]` to validate this spec before it enters the implementation pipeline
|
||||
- Run `/ux-design [next-screen]` to continue designing remaining screens or flows
|
||||
- Run `/gate-check pre-production` once all key screens have approved UX specs
|
||||
|
||||
Reference in New Issue
Block a user