/map-systems

name: map-systems
description: "Decompose a concept into individual systems, map dependencies, prioritize design order, create the systems index."
argument-hint: "[next | system-name] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Agent, Bash(bash "*/.claude/skills/map-systems/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,project.stage`

Resolved above — use as-is; `--review` overrides `review_mode`. No block → defaults in `.claude/docs/config-resolution.md`.

Map Systems

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).

See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt). In collaborative mode the system list, dependency, priority and write approvals are separate questions: each waits for its answer before the next step runs.

**`docs.density`** — it controls per-section *depth*, where `workflow` controls which sections exist. `modes.rigor` sets both together; set `docs.density` explicitly to vary depth alone: `terse` (the default, via `rigor: minimal`) = one-line system descriptions; `balanced` = a brief paragraph per system + dependency notes (`rigor: standard`); `thorough` = full system-by-system rationale + relationship analysis. Apply it to every section you author.

> **Where the per-system prose goes.** `templates/systems-index.md`'s Systems > Enumeration is a fixed-column table with no description column, so at > `balanced` and `thorough` the prose belongs in `## Overview` — one short > paragraph per system at `balanced`, plus relationship analysis at `thorough` — > and in the `## Dependency Map` layer notes. **Do not add a column to the > enumeration table** — it is a fixed contract in > `.claude/docs/templates/systems-index.md`, and its consumers > (`/design-system` §6 and §7, `/create-epics`) are written against the columns it > defines. Widening it is a schema change, not a formatting choice. > > **How the consumers actually read it.** Nothing parses this table > positionally. The two scripts that mention `systems-index.md` > (`gdd-structure-check.sh:51`, `review-scope.sh:40`) match it **by filename** in a > `case` statement and parse no columns at all; the two skills key on the > **`Category` column by name** (`design-system:229`, `:780`). So `Category` is > the column that must never be renamed or dropped, and the table stays a fixed > contract because every consumer is written against the set of columns the > template defines. > At `terse`, the table plus a one-paragraph `## Overview` is the whole output.

**`workflow`** (see `.claude/docs/workflow-modes.md`):

• `full` / `standard` — required before `/design-system` (systems must be mapped

before per-system GDDs are authored).

• `minimal` — not required (the game brief replaces the systems index). Can

still be run voluntarily.

---

Phase 1: Read Concept (Required Context)

Read the game concept and any existing design work. This provides the raw material for systems decomposition. Read each doc by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.

**Required:**

• Read `design/gdd/game-concept.md` (at `minimal`, read `design/game-brief.md`

instead) — **fail with a clear message if neither is found**: > "No game concept found. 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: s