Studio Help — What Do I Do Next?

🌱 ShiningPlague-adopted. Originally Donchitos; battle-tested on a shipped Godot project. Upstream canonical phase logic preserved + workstream/adoption awareness layered on.

This skill is read-only — it reports findings but writes no files.

Figures out where you are in the game development pipeline and tells you what comes next. Lightweight — not a full audit. For full gap analysis, use /project-stage-detect.

If an artifact named here is absent: say so plainly in one line, skip that step, and continue. Never invent the file to satisfy a checklist, and never fail a close because an optional artifact was never created.

When to fire

• Designer asks: "where are we", "what should I do now", "what's next", "I'm stuck", "I don't know", "status", "help"
• Session-start hook output PHASE ARTIFACT STATUS surfaced an unresolved gap
• After a major skill fires — recommend the next canonical step

Step 1: Read the Catalog

Read .claude/docs/workflow-catalog.yaml. Authoritative list of all phases, their steps, required/optional flags, and artifact globs.

Step 1b: Find Skills Not in the Catalog

Glob .claude/skills/*/SKILL.md. For each, extract the name: field from frontmatter.

Compare against command: values in the catalog. Any skill whose name doesn't appear in the catalog is uncataloged — usable but not phase-gated.

Collect for Step 7 footer:

### Also installed (not in workflow)
- `/skill-name` — [description from SKILL.md frontmatter]

Show only if at least one uncataloged skill exists. Limit to the 10 most relevant for current phase.

Step 2: Determine Current Phase

1. Read production/stage.txt — authoritative. Map to catalog phase key:
   • "not-started" → the seeded default, not a phase. No gate has been cleared; fall through to step 2 and infer from artifacts.
   • "Concept" → concept
   • "Systems Design" → systems-design
   • "Technical Setup" → technical-setup
   • "Pre-Production" → pre-production
   • "Production" → production
   • "Polish" → polish
   • "Release" → release
2. If missing (a --no-scaffold install) or still not-started, infer phase from artifacts (most-advanced match wins). The installer seeds this stack blank, so judge these on content, not existence — an unfilled template is not an artifact, and a file still carrying the scaffold-seed: unwritten marker near the top counts as absent (.claude/docs/doc-stack.md § Seeded is not written):
   • src/ has 10+ source files → production
   • production/epics/**/*.md exists → pre-production
   • docs/adr/[0-9]*.md exists → technical-setup (NNN-<slug>.md only; the leading digit excludes the seeded docs/adr/TEMPLATE.md)
   • docs/gdd/systems-index.md has rows in its systems table → systems-design
   • docs/gdd/game-concept.md has a written elevator pitch (not the bracketed […] prompt text) → concept
   • Nothing → concept (fresh project)

Step 3: Read Session Context

Read production/session-state/active.md. Extract:

• What was most recently worked on
• In-progress tasks or open questions
• Current epic/feature/task from STATUS block

This personalizes the output.

Step 4: Read Per-Workstream State (studio addition)

Glob production/workstreams/*.md. For each, extract:

• Current Phase: line
• In Progress section content
• Blocked section content
• Open Questions section content

Report per-workstream phase + what's in flight + blockers.

Step 5: Read Open Adoption TODOs (studio addition)

Read production/session-state/active.md. Look for 🚨 OPEN ADOPTION PLAN TODOs section. List unresolved items.

Also check docs/adoption-plan-*.md for any unchecked items not yet surfaced.

Step 6: Read Open Specs (studio addition)

Glob docs/specs/*.md. For each, extract Status (🚧 IN PROGRESS / ✅ FINAL / 🗄️ ARCHIVED). List in-progress specs — paused work waiting to resume.

Step 7: Check Step Completion for Current Phase

For each step in current phase (from catalog):

Artifact-based checks

If step has artifact.glob:

• Use Glob to check
• If min_count specified, verify count
• If artifact.pattern specified, use Grep to verify pattern
• Complete = artifact condition met
• Incomplete = artifact missing or pattern not found

If step has artifact.note (no glob):

• Mark MANUAL — ask user

If step has no artifact field:

• Mark UNKNOWN — not trackable

Special case: production phase — read sprint-status.yaml

When current phase is production, check production/sprint-status.yaml before glob-based story checks. The installer seeds it status: none with an empty stories: [] — that is "no sprint has been planned yet", not a sprint with no stories. Once a sprint exists, read it:

• Stories status: in-progress → "currently active"
• status: ready-for-dev → "next up"
• status: done → count as complete
• status: blocked → surface as blocker

Skip glob check for implement and story-done steps — YAML is authoritative.

Special case: repeatable: true (non-production)

For repeatable steps outside production (e.g. "System GDDs"), artifact check tells whether any work has been done. Label differently — show detected, note it may be ongoing.

Step 8: Determine Recommended Next Canonical Action

Priority order:

1. Project canonical phase gap (foundational) — if Concept/Systems-Design artifacts missing, recommend canonical skill (e.g., /design-system game-concept if pointer-only).
2. Workstream-specific work — if foundational gaps closed, check which workstream the designer was last on (active.md priorities[0]) and recommend the next canonical step.
3. In-progress paused work — if a spec is 🚧 IN PROGRESS, recommend resuming.
4. Open adoption TODOs — surface unresolved items even if recommending phase work.

Step 9: Present Output

Keep it short and direct. Quick orientation, not a report.

## Where You Are: [Phase Label]

**In progress:** [from active.md, if any]

### ✓ Done
- [completed step name]

### → Next up (recommended)
**[Step name]** — [description]
Command: `[/command]`

### Workstream Status

| Workstream | Phase | In Progress | Blocked |
|---|---|---|---|
| Combat | Production | [item] | — |
| Narrative | Concept | — | [blocker] |

### Open Adoption TODOs
- [item 1]
- [item 2]

### Open Specs (paused)
- 🚧 [spec path] — [topic]

### ~ Also available (optional)
- **[Step name]** — [description] → `/command`

### Coming up after that
- [Next step name] (`/command`)

---
Getting close to the **[next phase]** gate → run `/gate-check` when you're ready.

Formatting rules:

• ✓ for confirmed complete
• → for the recommended next step (only one — the first blocker)
• ~ for optional steps available now
• Show commands inline as backtick code
• For MANUAL steps, ask: "I can't tell if [step] is done — has it been completed?"
• Keep the tone friendly and orienting — this is a helpful signpost, not a compliance report.

Step 10: Gate Warning (if close)

If all required steps in current phase are complete (or nearly), add:

"You're close to the [Current] → [Next] gate. Run /gate-check when ready."

If multiple required steps remain, skip the gate warning.

Step 11: Escalation Paths

If user seems stuck or confused, add:

---
Need more detail?
- `/project-stage-detect` — full gap analysis with all missing artifacts listed
- `/gate-check` — formal readiness check for your next phase
- `/start` — re-orient from scratch

Only show if input suggested confusion ("I don't know", "stuck", "lost", "not sure").

Cross-skill awareness

• After firing this skill, if user picks canonical recommendation, the natural next skill fires per team-orchestrator.md activity chain.
• Pair with /project-stage-detect (also project-local) — that skill does the deep gap audit; this one does the day-to-day "what's next" framing.

Reference files (project)

• .claude/docs/workflow-catalog.yaml — canonical phase pipeline
• production/stage.txt — current canonical phase
• production/workstreams/*.md — per-workstream state
• production/session-state/active.md — open TODOs + priorities
• docs/specs/*.md — paused brainstorm specs
• docs/adoption-plan-*.md — historical adoption plans written by /adopt
• tools/generate_session_context.sh — OPTIONAL, project-owned. The template never ships it; .claude/hooks/session-start.sh runs it only if the project wrote one. Absent by default.

Failure modes

• ❌ Listing all phase artifacts as plain status — that's /project-stage-detect's job. This skill RECOMMENDS next action.
• ❌ Asking "what do you want to do?" without recommending. Always recommend.
• ❌ Forgetting to read active.md adoption TODOs section.
• ❌ Re-scanning all globs when session-start hook already did it.

Collaborative Protocol

• Never auto-run the next skill. Recommend it, let the user invoke it.
• Ask about MANUAL steps rather than assuming complete or incomplete.
• Match the user's tone — if they sound stressed ("I'm totally lost"), be reassuring and give one action, not a list of six.
• One primary recommendation — user should leave knowing exactly one thing to do next.