# Skill Test Spec: /map-systems

## Skill Summary

`/map-systems` decomposes a game concept into a systems index. It reads the
approved game concept and pillars, enumerates both explicit and implicit systems,
maps dependencies between systems, assigns priority tiers (MVP / Vertical Slice /
Alpha / Full Vision), and organizes systems into a layered design order
(Foundation → Core → Feature → Presentation). The output is written to
`design/systems-index.md` after user approval.

This skill is required between game concept approval and per-system GDD creation
— it is a mandatory gate in the pipeline. In `full` review mode, CD-SYSTEMS
(creative-director) and TD-SYSTEM-BOUNDARY (technical-director) spawn in parallel
after the decomposition is drafted. In `lean` or `solo` mode, both gates are
skipped. The skill writes to `design/systems-index.md`.

---

## Static Assertions (Structural)

Verified automatically by `/skill-test static` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keywords: COMPLETE, BLOCKED
- [ ] Contains "May I write" collaborative protocol language (for systems-index.md)
- [ ] Has a next-step handoff at the end (`/design-system`)
- [ ] Documents gate behavior: CD-SYSTEMS + TD-SYSTEM-BOUNDARY in parallel in full mode

---

## Director Gate Checks

In `full` mode: CD-SYSTEMS (creative-director) and TD-SYSTEM-BOUNDARY
(technical-director) spawn in parallel after the systems decomposition is drafted
and before `design/systems-index.md` is written.

In `lean` mode: both gates are skipped. Output notes:
"CD-SYSTEMS skipped — lean mode" and "TD-SYSTEM-BOUNDARY skipped — lean mode".

In `solo` mode: both gates are skipped with equivalent notes.

---

## Test Cases

### Case 1: Happy Path — Game concept exists, 5-8 systems identified

**Fixture:**
- `design/gdd/game-concept.md` exists with Core Mechanics and MVP Definition sections
- `design/gdd/game-pillars.md` exists with ≥1 pillar defined
- No `design/systems-index.md` exists yet
- `production/session-state/review-mode.txt` contains `full`

**Input:** `/map-systems`

**Expected behavior:**
1. Skill reads game-concept.md and game-pillars.md
2. Identifies 5-8 systems (explicit + implicit)
3. Maps dependencies between systems and assigns layers
4. CD-SYSTEMS and TD-SYSTEM-BOUNDARY spawn in parallel and return APPROVED
5. Asks "May I write `design/systems-index.md`?"
6. Writes systems-index.md after approval
7. Updates `production/session-state/active.md`

**Assertions:**
- [ ] Between 5 and 8 systems are identified (not fewer, not more without explanation)
- [ ] CD-SYSTEMS and TD-SYSTEM-BOUNDARY spawn in parallel (not sequentially)
- [ ] Both gates complete before the "May I write" ask
- [ ] "May I write `design/systems-index.md`?" is asked before writing
- [ ] systems-index.md is NOT written without approval
- [ ] Session state is updated after writing
- [ ] Verdict is COMPLETE

---

### Case 2: Failure Path — No game concept found

**Fixture:**
- `design/gdd/game-concept.md` does NOT exist
- `design/gdd/` directory may be empty or absent

**Input:** `/map-systems`

**Expected behavior:**
1. Skill attempts to read `design/gdd/game-concept.md`
2. File not found
3. Skill outputs: "No game concept found. Run `/brainstorm` to create one, then return to `/map-systems`."
4. Skill exits without creating systems-index.md

**Assertions:**
- [ ] Skill outputs a clear error naming the missing file path
- [ ] Skill recommends `/brainstorm` as the next action
- [ ] No systems-index.md is created
- [ ] Verdict is BLOCKED

---

### Case 3: Director Gate — CD-SYSTEMS returns CONCERNS (missing core system)

**Fixture:**
- Game concept exists
- `production/session-state/review-mode.txt` contains `full`
- CD-SYSTEMS gate returns CONCERNS: "The [core-system] is implied by the concept but not identified"

**Input:** `/map-systems`

**Expected behavior:**
1. Systems are drafted (5-8 initial systems identified)
2. CD-SYSTEMS gate returns CONCERNS naming the missing core system
3. TD-SYSTEM-BOUNDARY returns APPROVED
4. Skill surfaces CD-SYSTEMS concerns to user
5. User is asked: revise systems list to add the missing system, or proceed as-is
6. If revised: updated systems list shown before "May I write" ask

**Assertions:**
- [ ] CD-SYSTEMS concerns are shown to the user before writing
- [ ] Skill does NOT auto-write systems-index.md while CONCERNS are unresolved
- [ ] User is given the option to revise or proceed
- [ ] Revised systems list is re-shown after revision before final "May I write"

---

### Case 4: Edge Case — systems-index.md already exists

**Fixture:**
- `design/gdd/game-concept.md` exists
- `design/systems-index.md` already exists with N systems

**Input:** `/map-systems`

**Expected behavior:**
1. Skill reads the existing systems-index.md and presents its current state
2. Skill asks: "systems-index.md already exists with [N] systems. Update with new systems, or review and revise priorities?"
3. User chooses an action
4. Skill does NOT silently overwrite the existing index

**Assertions:**
- [ ] Skill detects and reads the existing systems-index.md before proceeding
- [ ] User is offered update/review options — not auto-overwritten
- [ ] Existing system count is presented to the user
- [ ] Skill does NOT proceed with a full re-decomposition without user choosing to do so

---

### Case 5: Director Gate — Lean mode and solo mode both skip gates, noted

**Fixture (lean mode):**
- Game concept exists
- `production/session-state/review-mode.txt` contains `lean`

**Lean mode expected behavior:**
1. Systems are decomposed and drafted
2. Both CD-SYSTEMS and TD-SYSTEM-BOUNDARY are skipped
3. Output notes: "CD-SYSTEMS skipped — lean mode" and "TD-SYSTEM-BOUNDARY skipped — lean mode"
4. "May I write" ask proceeds directly

**Assertions (lean mode):**
- [ ] Both gate skip notes appear in output
- [ ] Skill proceeds to "May I write" without gate approval
- [ ] systems-index.md is written after user approval

**Fixture (solo mode):**
- Same game concept, `production/session-state/review-mode.txt` contains `solo`

**Solo mode expected behavior:**
1. Same decomposition workflow
2. Both gates skipped — noted in output with "solo mode"
3. "May I write" ask proceeds

**Assertions (solo mode):**
- [ ] Both skip notes appear with "solo mode" label
- [ ] Behavior is otherwise identical to lean mode for this skill

---

## Protocol Compliance

- [ ] Reads game-concept.md and game-pillars.md before any decomposition
- [ ] "May I write `design/systems-index.md`?" asked before writing
- [ ] systems-index.md is NOT written without user approval
- [ ] CD-SYSTEMS and TD-SYSTEM-BOUNDARY spawn in parallel in full mode
- [ ] Skipped gates noted by name and mode in lean/solo output
- [ ] Ends with next-step handoff: `/design-system [next-system]`

---

## Coverage Notes

- Circular dependency detection (System A depends on System B which depends on A)
  is part of the dependency mapping phase — not independently fixture-tested here.
- Priority tier assignment (MVP heuristics) is evaluated as part of the Case 1
  collaborative workflow rather than independently.
- The `next` argument mode (handing off the highest-priority undesigned system to
  `/design-system`) is not tested here — it is a post-index-creation convenience.
