Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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)
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:
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:
MVP Foundation systems first
MVP Core systems second
MVP Feature systems third
Vertical Slice Foundation/Core systems
...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:
Question -> Options -> Decision -> Draft -> Approval at every step
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
"May I write to [filepath]?" before every file write
Incremental writing: Update the systems index after each system is designed
Handoff: Individual PRD authoring is owned by /design-system, which handles
incremental section writing, cross-referencing, design review, and index updates
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]
