Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/help.md

# Skill Test Spec: /help

## Skill Summary

`/help` tells the user where they are in the pipeline and the one thing to do
next. It is read-only and declares the Haiku tier (`model: haiku`), which is
used only when the user types `/help` in Manual mode — in auto mode, or when
Claude starts the skill itself, the session model runs it
(`.claude/docs/model-tiers.md`). Before it runs, it is handed the resolved
config block (`project.stage`, `workflow`) and the output of
`.claude/scripts/story-status.sh`; it reads the session checkpoint itself (Step 3). It then reads
`.claude/docs/workflow-catalog.yaml`, resolves step completion for the current
phase with one call to `bash .claude/scripts/artifact-check.sh --phase [phase]`,
and in Production reads `production/sprint-status.yaml`.

When `workflow` resolves to `minimal` (the default, because `modes.rigor`
defaults to `minimal`) it skips the phase ladder, reads the session checkpoint
(Step 3), and walks the minimal path (Step 4m): engine →
`design/game-brief.md` → stories → `/dev-story` ↔ `/story-done`. The optional
argument is **what the user just finished or is stuck
on** — the skill uses it to advance past the named step, and confusion language
in it adds an escalation footer. It is not a topic filter.

Output is a short "Where You Are" block with `✓ Done`, exactly one `→ Next up`,
optional `~ Also available`, and `Coming up after that`. The verdict line is
`Verdict: **COMPLETE** — next steps identified.` No files are written and no
director gates are invoked.

---

## Static Assertions (Structural)

Checked against the SKILL.md by `/skill-test spec` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Frontmatter sets `model: haiku`
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keyword: COMPLETE
- [ ] Does NOT contain "May I write" language, and `allowed-tools` has no Write or Edit (skill is read-only)
- [ ] Has a next-step handoff (one `→ Next up` recommendation plus escalation paths)

---

## Director Gate Checks

None. `/help` is a read-only navigation skill. No director gates apply.

---

## Test Cases

### Case 1: Happy Path — Production stage with active sprint

**Fixture:**
- `project.yaml` sets `project.stage: Production` and `modes.rigor: standard`
  (so `workflow` resolves to `standard`)
- `production/sprints/sprint-004.md` exists
- `production/sprint-status.yaml` lists one story `status: in-progress`, two
  `status: ready-for-dev`, three `status: done`, and one `status: blocked` with a
  `blocker` field
- `production/session-state/active.md` has a STATUS block naming the in-progress story

**Input:** `/help`

**Expected behavior:**
1. Skill takes `project.stage: Production` and `workflow: standard` from the config block
2. Skill reads `.claude/docs/workflow-catalog.yaml` and runs
   `bash .claude/scripts/artifact-check.sh --phase production`
3. Skill reads `production/sprint-status.yaml`: the in-progress story is
   "currently active", ready-for-dev stories are "next up", done stories count as
   complete, the blocked story is named with its `blocker` text
4. Because `active.md` shows an active task, it is surfaced prominently at the top:
   "It looks like you were working on [story]"
5. Output uses the Step 7 shape headed `## Where You Are: Production`, with a
   single `→ Next up (REQUIRED)` step
6. Verdict is COMPLETE

**Assertions:**
- [ ] Heading reads `## Where You Are: Production`
- [ ] `production/sprint-status.yaml` is read; the in-progress story is surfaced as currently active
- [ ] The blocked story appears with its `blocker` field
- [ ] Exactly one `→ Next up (REQUIRED)` step is shown (not a list of all skills)
- [ ] The in-progress story from `active.md` is surfaced at the top ("It looks like you were working on …")
- [ ] Verdict is COMPLETE
- [ ] No files are written

---

### Case 2: Concept Stage — engine configured, no concept document

**Fixture:**
- `project.yaml` sets `project.stage: Concept`, `modes.rigor: full`, and
  `engine.name: "Godot"` (`full`, because at `standard` the art bible is
  required only when visual-asset stories exist — `.claude/docs/workflow-modes.md`
  — and a Concept-stage project has no stories to decide it by)
- No `design/gdd/game-concept.md`, no `design/art/art-bible.md`, no
  `design/gdd/systems-index.md`, no sprint files

**Input:** `/help`

**Expected behavior:**
1. Skill maps `Concept` to the catalog phase `concept`
2. `artifact-check.sh --phase concept` reports `engine-setup` PRESENT (matched by
   `engine.name` in `project.yaml`) and `game-concept`, `art-bible`, `map-systems` ABSENT
3. `✓ Done` lists Engine Setup
4. `→ Next up (REQUIRED)` is **Game Concept Document** with command `/brainstorm`
5. `Coming up after that` lists Art Bible (`/art-bible`) and Systems Map (`/map-systems`)
6. Verdict is COMPLETE

**Assertions:**
- [ ] Heading reads `## Where You Are: Concept`
- [ ] Engine Setup is shown under `✓ Done` (not reported missing)
- [ ] `→ Next up` is Game Concept Document via `/brainstorm`
- [ ] `/art-bible` and `/map-systems` appear under "Coming up after that", in that order
- [ ] No Production-stage skill (e.g. `/dev-story`, `/sprint-plan`) is suggested
- [ ] Verdict is COMPLETE

---

### Case 3: No stage recorded — phase inferred from artifacts

**Fixture:**
- `project.yaml` sets `modes.rigor: standard` and has no `project.stage`
- No `production/stage.txt`
- `design/gdd/game-concept.md` and `design/gdd/systems-index.md` exist
- No `docs/architecture/adr-*.md`, no `production/epics/**/story-*.md`, code root empty

**Input:** `/help`

**Expected behavior:**
1. Config block reports `project.stage` as not set
2. Skill applies the Step 2 artifact inference (most-advanced match wins):
   `design/gdd/systems-index.md` exists and nothing further → `systems-design`
3. Skill reports the inferred phase normally with the Step 7 shape
4. `→ Next up (REQUIRED)` is System GDDs via `/design-system`. The catalog's
   `design-system` step has only a `note:` check, so `artifact-check.sh` reports
   it `NO_CHECK` with a note — a **MANUAL** step: the skill asks whether any
   system GDD is already done instead of asserting that none is
5. The input has no confusion language, so the Step 9 escalation block is not shown
6. Verdict is COMPLETE

**Assertions:**
- [ ] Skill does not stop or error when no stage is recorded
- [ ] Inferred phase is Systems Design (heading `## Where You Are: Systems Design`), not Concept
- [ ] `→ Next up` is System GDDs via `/design-system`
- [ ] The skill asks the user whether any system GDD is already done (MANUAL step), rather than reporting System GDDs as done or as not started
- [ ] The "Need more detail?" escalation block (`/project-stage-detect`, `/gate-check`, `/start`) is NOT shown
- [ ] Verdict is COMPLETE

---

### Case 4: Argument — user names the step they finished and says they are unsure

**Fixture:**
- `project.yaml` sets `project.stage: Systems Design` and `modes.rigor: standard`
- `design/gdd/systems-index.md` lists two MVP systems, both `Status: Approved`,
  and both system GDDs exist
- No `design/gdd/gdd-cross-review-*.md`
- The catalog's `design-review` step has no artifact check (`NO_CHECK`)

**Input:** `/help just finished design-review, not sure what's next`

**Expected behavior:**
1. The argument is read as the step the user just finished (Step 5), not as a topic filter
2. Skill advances past Per-System Design Review even though its artifact check is `NO_CHECK`
3. `→ Next up (REQUIRED)` is Cross-GDD Review via `/review-all-gdds`
4. "not sure" is confusion language, so the Step 9 "Need more detail?" block is
   appended with `/project-stage-detect`, `/gate-check` and `/start`
5. The `/settings` rigor line is NOT shown: the user does not sound overwhelmed by
   process and the project has not outgrown `standard` (no `settings-guidance.md § 4` trigger fires)
6. Verdict is COMPLETE

**Assertions:**
- [ ] Per-System Design Review is treated as done because the user named it
- [ ] `→ Next up` is Cross-GDD Review via `/review-all-gdds`
- [ ] Escalation block lists `/project-stage-detect`, `/gate-check` and `/start`
- [ ] No `/settings` rigor-change line appears
- [ ] Verdict is COMPLETE

---

### Case 5: Director Gate Check — minimal path, no gate and no gate-check route

**Fixture:**
- `project.yaml` has `engine.name: "Godot"` and no `modes` block (`modes.rigor`
  defaults to `minimal`, so `workflow` resolves to `minimal`)
- `design/game-brief.md` exists
- `production/epics/core/story-001.md` is `Status: Complete`,
  `story-002.md` is `Status: In Progress`, `story-003.md` is `Status: Ready`
- Neither `active.md` (its CHECKPOINT names story-002 as the current task, with
  **Next step:** `/dev-story` on it) nor the git log (no commit mentions
  story-002) says story-002's implementation is written

**Input:** `/help`

**Expected behavior:**
1. `workflow: minimal` sends the skill past the rest of Step 2; `project.stage`
   is not mapped
2. Skill reads `active.md`'s STATUS and CHECKPOINT blocks (Step 3), then goes to
   Step 4m
3. Skill runs `bash .claude/scripts/artifact-check.sh --path minimal`
4. The injected `story-status.sh` list has story-002 on the first `IN_PROGRESS`
   line; the skill does not re-run the script or re-rank the stories
5. Output uses the minimal shape: `## Where You Are: Minimal path — 1 of 3 stories complete`,
   with `✓ Done` giving the count of complete stories, not their titles
6. `→ Next up` is story-002 with `/dev-story [story-002 path]`
7. No phase label, no gate line; the concept doc, art bible, systems map, GDDs,
   sprint plan and `/gate-check` are not presented as required
8. No director agents are spawned and no write tool is called

**Assertions:**
- [ ] Heading reads `Minimal path — 1 of 3 stories complete`
- [ ] `active.md`'s checkpoint is read before the next step is chosen (Step 3 runs at `minimal`)
- [ ] `→ Next up` is story-002 via `/dev-story`, not story-003
- [ ] No `/gate-check` line and no "Approaching … gate" line appear
- [ ] Game concept, art bible, systems map and GDDs are not listed as next steps
- [ ] No director gate is invoked and no gate IDs appear in output
- [ ] No write tool is called
- [ ] Verdict is COMPLETE

---

### Case 6: Minimal path — the checkpoint says the work is written

**Fixture:**
- As Case 5, except `active.md`'s CHECKPOINT reads
  **Next step:** `/story-done production/epics/core/story-002.md` (what
  `/dev-story` writes when it finishes a story)

**Input:** `/help`

**Expected behavior:**
1. Step 3 runs at `minimal` and finds the checkpoint's next step
2. story-002 is still on the first `IN_PROGRESS` line, but `active.md` says its
   implementation is written, so `→ Next up` is story-002 with
   `/story-done [story-002 path]`
3. Verdict is COMPLETE

**Assertions:**
- [ ] `→ Next up` is story-002 via `/story-done`, not `/dev-story`
- [ ] story-002 is not counted or listed as complete
- [ ] Verdict is COMPLETE

---

### Case 7: Minimal path — only a blocked story and an unknown status remain

**Fixture:**
- As Case 5, except `story-002.md` is `Status: Blocked` (its file says it waits
  on the art for the player sprite) and `story-003.md` is `Status: Draft`

**Input:** `/help I'm stuck`

**Expected behavior:**
1. The injected list has no `IN_REVIEW`, `IN_PROGRESS` or `TODO` line: story-002
   is on a `BLOCKED` line and story-003 on an `OTHER` line (`Draft`)
2. The skill names story-002 with its blocker and story-003 with its status as
   written, and says nothing can be built next
3. It does **not** say the build order is done, and does not offer the "three
   ways on" of the every-story-Complete branch
4. `→ Next up` is clearing the first of them — story-002's blocker
5. "stuck" is confusion language, so the Step 9 "Need more detail?" block is
   appended — without its `/gate-check` line, since the minimal path has no
   phase gates
6. Verdict is COMPLETE

**Assertions:**
- [ ] story-002 is named with its blocker; story-003 is named with status `Draft`
- [ ] Neither story is recommended to `/dev-story` or `/story-done`
- [ ] The output does not say the build order is done
- [ ] Heading reads `Minimal path — 1 of 3 stories complete`
- [ ] The escalation block appears and has no `/gate-check` line
- [ ] Verdict is COMPLETE

---

## Protocol Compliance

- [ ] Uses the injected config block for `project.stage` and `workflow` instead of re-reading them
- [ ] Resolves step completion with one `artifact-check.sh` call, not a Glob per step
- [ ] Gives exactly one primary (`→ Next up`) recommendation
- [ ] Never auto-runs the recommended skill
- [ ] Asks the user about `MANUAL` steps rather than assuming them done or not done
- [ ] Does not write any files
- [ ] Verdict is COMPLETE in all cases

---

## Coverage Notes

- The case where every story in `sprint-status.yaml` is done is not separately
  tested; the Step 8 gate warning would then apply.
- At `workflow: full` every optional step is listed under `~ Also available`;
  Case 2 runs at `full` only so that the art bible is required, and does not
  assert that listing.
- The minimal path's "every story Complete" branch (three ways on: play the
  build, `/create-stories`, `/settings`) is not separately tested.