/map-systems

name: map-systems
description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index."
argument-hint: "[next | system-name] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite, Task
model: sonnet

When this skill is invoked:

Parse Arguments

Two modes:

• **No argument**: `/map-systems` — Run the full decomposition workflow (Phases 1-5)

to create or update the systems index.

• **`next`**: `/map-systems next` — Pick the highest-priority undesigned system

from the index and hand off to `/design-system` (Phase 6).

Also resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 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.

---

Phase 1: Read Concept (Required Context)

Read the game concept and any existing design work. This provides the raw material for systems decomposition.

**Required:**

• Read `design/gdd/game-concept.md` — **fail with a clear message if missing**:

> "No game concept found at `design/gdd/game-concept.md`. Run `/brainstorm` first > to create one, then come back to decompose it into systems."

**Optional (read if they exist):**

• Read `design/gdd/game-pillars.md` — pillars constrain priority and scope
• Read `design/gdd/systems-index.md` — if exists, **resume** from where it left off

(update, don't recreate from scratch)

• Glob `design/gdd/*.md` — check which system GDDs already exist

**If the systems index already exists:**

• Read it and present current status to the user
• Use `AskUserQuestion` to ask:

"The systems index already exists with [N] systems ([M] designed, [K] not started). What would you like to do?"

• Options: "Update the index with new systems", "Design the next undesigned system",

"Review and revise priorities"

---

Phase 2: Systems Enumeration (Collaborative)

Extract and identify all systems the game needs. This is the creative core of the skill — it requires human judgment because concept docs rarely enumerate every system explicitly.

Step 2a: Extract Explicit Systems

Scan the game concept for directly mentioned systems and mechanics:

• Core Mechanics section (most explicit)
• Core Loop section (implies what systems drive each loop tier)
• Technical Considerations section (networking, procedural generation, etc.)
• MVP Definition section (required features = required systems)

Step 2b: Identify Implicit Systems

For each explicit system, identify the **hidden systems** it implies. Games always need more systems than the concept doc mentions. Use this inference pattern:

• "Inventory" implies: item database, equipment slots, weight/capacity rules,

inventory UI, item serialization for save/load

• "Combat" implies: damage calculation, health system, hit detection, status effects,

enemy AI, combat UI (health bars, damage numbers), death/respawn

• "Open world" implies: streaming/chunking, LOD system, fast travel, map/minimap,

point of interest tracking, world state persistence

• "Multiplayer" implies: networking layer, lobby/matchmaking, state synchronization,

anti-cheat, network UI (ping, player list)

• "Crafting" implies: recipe database, ingredient gathering, crafting UI,

success/failure mechanics, recipe discovery/learning

• "Dialogue" implies: dialogue tree system, dialogue UI, choice tracking, NPC

state management, localization hooks

• "Progression" implies: XP system, level-up mechanics, skill tree, unlock

tracking, progression UI, progression save data

Explain in conversation text why each implicit system is needed (with examples).

Step 2c: User Review

Present the enumeration organized by category. For each system, show:

• Name
• Category
• Brief description (1 sentence)
• Whether it was explicit (from concept) or implicit (inferred)

Then use `AskUserQuestion` to capture feedback:

• "Are there systems missing from this list?"
• "Should any of these be combined or split?"
• "Are there systems listed that this game does NOT need?"

Iterate until the user approves the enumeration.

---

Phase 3: Dependency Mapping (Collaborative)

For each system, determine what it depends on. A system "depends on" another if it cannot function without that other system existing first.

Step 3a: Map Dependencies

For each system, list its dependencies. Use these dependency heuristics:

• **Input/output dependencies**: System A produces data System B needs
• **Structural dependencies**: System A provides the framework System B plugs into
• **UI dependencies**: Every gameplay system has a corresponding UI system that

depends on it (but UI is designed after the gameplay system)

Step 3b: Sort by Dependency Order

Arrange systems into layers: 1. **Foundation**: Systems with zero dependencies (designed and built first) 2. **Core**: Systems depending only on Foundation systems 3. **Feature**: Systems depending on Core systems 4. **Presentation**: UI and feedback systems that wrap gameplay systems 5. **Polish**: Meta-systems, tutorials, analytics, accessibility

Step 3c: Detect Circular Dependencies

Check for cycles in the dependency graph. If found:

• Highlight them to the user
• Propose resolutions (interface abstraction, simultaneous design, breaking the

cycle by defining a contract between the two systems)

Step 3d: Present to User

Show the dependency map as a layered list. Highlight:

• Any circular dependencies
• Any "bottleneck" systems (many others depend on them — these are high-risk)
• Any systems with no dependents (leaf nodes — lower risk, can be designed late)

Use `AskUserQuestion` to ask: "Does this dependency ordering look right? Any dependencies I'm missing or that should be removed?"

**Review mode check** — apply before spawning TD-SYSTEM-BOUNDARY:

• `solo`