help

Studio Help -- What Do I Do Next?

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

This skill figures out where the project is in the workflow and tells the user what comes next. It is lightweight -- not a full audit. For a full gap analysis, use /project-stage-detect after that skill is migrated.

---

Step 1: Read the Catalog

Read .github/docs/workflow-catalog.yaml. This is the authoritative list of phases, their ordered steps, whether each step is required or optional, and the artifact globs that indicate completion.

---

Step 2: Determine Current Phase

Check in this order:

1. Read production/stage.txt. If it exists and has content, treat it as the authoritative stage name.
2. If production/stage.txt is missing, infer phase from artifacts, using the most advanced match:
   • src/ has 10 or more source files -> production
   • files exist in production/epics/ or production/sprints/ -> pre-production
   • docs/architecture/adr-*.md exists -> technical-setup
   • design/gdd/systems-index.md exists -> systems-design
   • design/gdd/game-concept.md exists -> concept
   • otherwise -> concept

---

Step 3: Read Session Context

Read production/session-state/active.md if it exists. Extract:

• what was most recently worked on,
• any in-progress tasks or open questions,
• current epic, feature, or task from a STATUS block if present.

Use this to personalize the answer.

---

Step 4: Check Step Completion for the Current Phase

For each step in the current phase from the catalog:

Artifact-based checks

If the step has artifact.glob:

• use Glob to check whether matching files exist,
• respect min_count if present,
• if artifact.pattern exists, use Grep to confirm the pattern in the matched file,
• mark the step complete only when the artifact condition is satisfied.

If the step has artifact.note and no glob:

• mark it MANUAL -- cannot be auto-detected.

If the step has no artifact:

• mark it UNKNOWN -- trackable only by user confirmation or session context.

Special case: repeatable steps

For repeatable steps, artifact detection shows that some work exists, not that the step is globally finished. Phrase results accordingly.

---

Step 5: Find Position and Identify Next Steps

Determine:

• the last confirmed complete required step,
• the first incomplete required step as the current blocker,
• any optional steps available now,
• the next required steps after the blocker.

If the user provided an argument such as finished design-review, use it to disambiguate an otherwise ambiguous position.

---

Step 6: Present Output

Keep the answer short and direct.

Use this structure:

## Where You Are: [Phase Label]

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

### Done
- [completed step]

### Next up (REQUIRED)
**[step name]** -- [description]
Command: `/command`

### Also available (OPTIONAL)
- **[step name]** -- [description] -> `/command`

### Coming up after that
- [next required step] (`/command`)

Formatting rules:

• one primary recommendation only,
• optional items are secondary,
• if a step is MANUAL, ask the user whether it has been completed,
• never auto-run the next skill.

If the user sounds lost or explicitly asks for more help, add these escalation paths:

• /project-stage-detect -- full gap analysis
• /gate-check -- formal readiness check for the next phase
• /start -- re-orient from scratch

Verdict: COMPLETE

---

Collaborative Protocol

• Never auto-run the next skill.
• Ask about manual steps instead of assuming.
• Match the user's tone.
• Leave the user with one clear next action.

Required artifacts:

• .github/docs/technical-preferences.md is populated
• docs/architecture/architecture.md exists
• at least 3 ADRs exist in docs/architecture/
• docs/architecture/control-manifest.md exists
• design/accessibility-requirements.md exists

Quality checks:

• architecture covers core systems
• technical preferences define conventions and budgets
• no unresolved foundation-layer architectural blockers remain

Pre-Production -> Production

Required artifacts:

• at least one sprint plan exists
• epics and stories exist in production/epics/
• key UX specs exist in design/ux/
• core architecture and control manifest exist

Recommended but non-blocking:

• a vertical slice exists and has been played
• a vertical slice playtest report exists

Quality checks:

• core loop has been validated as fun or intentionally accepted without a slice
• core fantasy is represented in available playtest evidence
• accepted ADRs exist for foundation/core systems

Production -> Polish

Required artifacts:

• active code exists in src/
• core mechanics are implemented end-to-end
• tests exist for logic and integration coverage
• at least one smoke-check result exists
• at least 3 playtest sessions are documented

Quality checks:

• tests pass
• no critical known blockers remain
• core loop matches design intent
• performance is within budget or explicit concerns are recorded

Polish -> Release

Required artifacts:

• release checklist exists or has been completed
• changelog or patch notes draft exists
• QA sign-off artifact exists
• localization and content-complete evidence exists where applicable

Quality checks:

• no critical, high, or medium-severity release blockers remain
• performance targets are met on target platforms
• packaging and release pipeline are validated

---

3. Run the Gate

For the selected transition:

• inspect each required artifact,
• evaluate quality checks using available docs,
• note missing items as blockers,
• note recommended-but-missing items as concerns.

If review mode is full or lean, spawn the relevant phase gates in parallel:

• creative-director -> CD-PHASE-GATE
• technical-director -> TD-PHASE-GATE
• producer -> PR-PHASE-GATE
• art-director -> AD-PHASE-GATE when visual direction is relevant

If review mode is solo, skip director gates and note that the result is based only on artifact and document checks.

Apply the strictest verdict when multiple gate reviewers disagree.

---

4. Output Format

Return the result in this form:

## Gate Check: [Current] -> [Target]

### Required Artifacts
- [item] -- PASS / FAIL

### Quality Checks
- [item] -- PASS / CONCERNS / FAIL

### Director Reviews
- [gate] -- READY / CONCERNS / NOT READY

### Blockers
1. [blocking issue]

### Concerns
1. [non-blocking issue]

### Verdict: [PASS / CONCERNS / FAIL]

Verdict rules:

• PASS: all required items satisfied, no blocking issues
• CONCERNS: non-blocking gaps remain, but advancement is still defensible
• FAIL: one or more required artifacts or quality gates are missing or not ready

---

5. Advancement Handling

If the verdict is PASS, ask the user whether to advance the stage. If yes:

• write the new stage name to production/stage.txt
• confirm that the stage file was updated

If the verdict is CONCERNS, ask whether the user wants to:

• revise blockers now,
• accept the risk and proceed,
• stop and review later.

If the verdict is FAIL, do not advance the stage. Provide the single most important next fix first.

Verdict: COMPLETE