/map-systems

name: map-systems
type: workflow
description: "Creates a visual and textual map of the project systems, services, data flows, and integration boundaries. Use when documenting system architecture or when the user mentions system map, architecture diagram, or service boundaries."
argument-hint: "[optional: 'next' to pick highest-priority undesigned system, or a system name to hand off to /design-system]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite
context: fork
agent: technical-director
effort: 3
when_to_use: "When decomposing a product concept into individual systems, mapping dependencies, and prioritizing design order"

When this skill is invoked:

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

---

2. Phase 1: Read Concept (Required Context)

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

**Required:**

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

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

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

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

(update, don't recreate from scratch)

• Glob `design/docs/*.md` — check which system PRDs 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"

---

3. Phase 2: Systems Enumeration (Collaborative)

Extract and identify all systems the product 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 product 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. Products 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, user 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 product does NOT need?"

Iterate until the user approves the enumeration.

---

4. 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 business system has a corresponding UI system that

depends on it (but UI is designed after the business 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 business 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