Software_development_department map-systems

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 that should be removed?"

---

5. Phase 4: Priority Assignment (Collaborative)

Assign each system to a priority tier based on what milestone it's needed for.

Step 4a: Auto-Assign Based on Concept

Use these heuristics for initial assignment:

• MVP: Systems mentioned in the concept's "Required for MVP" section, plus their Foundation-layer dependencies
• Vertical Slice: Systems needed for a complete experience in one area
• Alpha: All remaining business systems
• Full Vision: Polish, meta, and nice-to-have systems

Step 4b: User Review

Present the priority assignments in a table. For each tier, explain why systems were placed there.

Use

AskUserQuestion

to ask: "Do these priority assignments match your vision? Which systems should be higher or lower priority?"

Explain reasoning in conversation: "I placed [system] in MVP because the core loop requires it — without [system], the 30-second loop can't function."

Step 4c: Determine Design Order

Combine dependency sort + priority tier to produce the final design order:

1. MVP Foundation systems first
2. MVP Core systems second
3. MVP Feature systems third
4. Vertical Slice Foundation/Core systems
5. ...and so on

This is the order the team should write PRDs in.

---

6. Phase 5: Create Systems Index (Write)

Step 5a: Draft the Document

Using the template at

.claude/docs/templates/systems-index.md

, populate the systems index with all data from Phases 2-4:

• Fill the enumeration table
• Fill the dependency map
• Fill the recommended design order
• Fill the high-risk systems
• Fill progress tracker (all systems "Not Started" initially, unless PRDs already exist)

Step 5b: Approval

Present a summary of the document:

• Total systems count by category
• MVP system count
• First 3 systems in the design order
• Any high-risk items

Ask: "May I write the systems index to

design/docs/systems-index.md

?"

Wait for approval. Write the file only after "yes."

Step 5c: Update Session State

After writing, update

production/session-state/active.md

with:

• Task: Systems decomposition
• Status: Systems index created
• File: design/docs/systems-index.md
• Next: Design individual system PRDs

---

7. Phase 6: Design Individual Systems (Handoff to /design-system)

This phase is entered when:

• The user says "yes" to designing systems after creating the index
• The user invokes

  /map-systems [system-name]

• The user invokes

  /map-systems next

Step 6a: Select the System

• If a system name was provided, find it in the systems index
• If

  next

  was used, pick the highest-priority undesigned system (by design order)
• If the user just finished the index, ask: "Would you like to start designing individual systems now? The first system in the design order is [name]. Or would you prefer to stop here and come back later?"

Use

AskUserQuestion

for: "Start designing [system-name] now, pick a different system, or stop here?"

Step 6b: Hand Off to /design-system

Once a system is selected, invoke the

/design-system [system-name]

skill.

The

/design-system

skill handles the full PRD authoring process:

• Gathers context from product concept, systems index, and dependency PRDs
• Creates a file skeleton immediately
• Walks through all 8 required sections one at a time (collaborative, incremental)
• Cross-references existing docs to prevent contradictions
• Routes to specialist agents for domain expertise
• Writes each section to file as soon as it's approved
• Runs

  /design-review

  when complete
• Updates the systems index

Do not duplicate the /design-system workflow here. This skill owns the systems index;

/design-system

owns individual system PRDs.

Step 6c: Loop or Stop

After

/design-system

completes, use

AskUserQuestion

:

• "Continue to the next system ([next system name])?"
• "Pick a different system?"
• "Stop here for this session?"

If continuing, return to Step 6a.

---

8. Phase 7: Suggest Next Steps

After the systems index is created (or after designing some systems), suggest the appropriate next actions:

• "Run

  /design-system [system-name]

  to write the next system's PRD"
• "Run

  /design-review [path]

  on each completed PRD to validate quality"
• "Run

  /gate-check pre-production

  to check if you're ready to start building"
• "Prototype the highest-risk system with

  /prototype [system]

  "
• "Plan the first implementation sprint with

  /sprint-plan new

  "

---

Collaborative Protocol

This skill follows the collaborative design principle at every phase:

1. Question -> Options -> Decision -> Draft -> Approval at every step
2. AskUserQuestion at every decision point (Explain -> Capture pattern):
   • Phase 2: "Missing systems? Combine or split?"
   • Phase 3: "Dependency ordering correct?"
   • Phase 4: "Priority assignments match your vision?"
   • Phase 5: "May I write the systems index?"
   • Phase 6: "Start designing, pick different, or stop?" then hand off to

     /design-system

3. "May I write to [filepath]?" before every file write
4. Incremental writing: Update the systems index after each system is designed
5. Handoff: Individual PRD authoring is owned by

   /design-system

   , which handles incremental section writing, cross-referencing, design review, and index updates
6. Session state updates: Write to

   production/session-state/active.md

   after each milestone (index created, system designed, priorities changed)

Never auto-generate the full systems list and write it without review. Never start designing a system without user confirmation. Always show the enumeration, dependencies, and priorities for user validation.

Protocol

• Question: AskUserQuestion at every phase — missing systems, dependency ordering, priority assignments
• Options: Phase 2 — systems enumeration reviewed and adjusted collaboratively before proceeding
• Decision: User approves enumeration, dependency map, and priority tiers before writing
• Draft: Systems index summary shown before saving
• Approval: "May I write the systems index to

  design/docs/systems-index.md

  ?"

Output

Deliver exactly:

• Systems index saved to

  design/docs/systems-index.md

  — all systems enumerated with dependencies and MVP tier
• Dependency map — which systems must be designed before others
• Design order — priority-ranked list of systems to PRD next
• Next skill:

  /design-system [first-priority-system]