map-systems skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,docs.density

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

When this skill is invoked:

Parse Arguments

Two modes:

to create or update the systems index.

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

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

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

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; automationalwaysask categories always prompt).

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 = one-line system descriptions; balanced = a brief paragraph per system + dependency notes (default); 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):

before per-system GDDs are authored).

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

still be run voluntarily.

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

Phase 1: Read Concept (Required Context)

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

Required:

instead) — fail with a clear message if neither is found:

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

"No game concept found. Run /brainstorm first to create one, then come back

to decompose it into systems."

Optional (read if they exist):

(update, don't recreate from scratch)

• 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

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

If the systems index already exists:

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

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

"Review and revise priorities"

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

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 UI, item serialization for save/load

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