| name | map-systems |
| description | Decomposes the app concept into discrete systems, maps dependencies, prioritizes design order by upstream-first, and writes the systems index. Use after /brainstorm and /setup-framework, before authoring any individual PRD. |
| argument-hint | [no arguments | next] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write, Edit, AskUserQuestion |
| model | sonnet |
Map Systems
Translates the concept doc into a graph of systems with dependencies and a recommended design order. The systems index that this skill writes is the authoritative list /design-system reads to figure out what to write next.
Output: design/systems-index.md
Purpose / When to Run
Run when:
design/concept.md is complete and approved- The team needs a single source of truth for what systems exist
- New systems were discovered mid-design and the index needs updating
Argument next is a shortcut: re-reads the index and shows the next system in the priority order without rebuilding the whole list.
Inputs
design/concept.md (required)design/design-bible.md if present.claude/docs/technical-preferences.md- Existing
design/systems-index.md if updating
Outputs
Phase 1: Argument Handling
If argument is next:
- Read
design/systems-index.md
- Find the highest-priority system with status
Not started
- Print: "Next system to design: (priority , layer ). Run
/design-system <name> to start."
- Done — do not rebuild the index.
Otherwise, full mapping flow:
- If
design/systems-index.md exists, ask whether to refresh it, append new systems only, or rebuild from scratch.
Phase 2: Read Concept
Read design/concept.md. Extract:
- The one-liner
- The MVP scope (in v1) and cuts (out of v1)
- The primary metric
- The riskiest assumption
If concept doc is missing, stop:
"No design/concept.md found. Run /brainstorm first."
If concept is fragmentary (sections empty), warn: "Concept doc has [N] empty sections. Mapping with incomplete concept will produce a brittle systems list — recommend completing the concept first."
Phase 3: Propose System List
For a typical mobile app, propose a candidate list. Adapt to what the concept says — never copy this list verbatim. Use it as a checklist to make sure no obvious system is forgotten.
Standard candidate categories:
Foundation layer
- App shell / navigation chrome
- Authentication / session
- Persistence (local DB / cache / secure storage)
- Network client / API layer
- Error reporting / crash handling
- Logging
- Analytics
- Feature flags / remote config
- Theme / dark mode
- Localization
Core layer (concept-specific)
- The 1-3 systems that deliver the core JTBD from the concept doc — name them based on the concept
Supporting features
- Profile / account
- Settings
- Notifications (push + in-app)
- Sharing / deep links
- Onboarding
- Help / support
- Search
- Empty / error / offline screens
Monetization
- Paywall (if monetized)
- IAP / subscription management
- Receipt validation
- Restore purchases
Platform integrations
- Camera / media (if used)
- Maps / location (if used)
- Biometrics (if used)
- Background tasks (if used)
- Widgets (if used)
- App Clips / Instant Apps (if used)
Present the proposed list to the user as a draft. Ask:
- Prompt: "Which of these systems are in scope for v1? Mark each."
- Use multi-select if your interface supports it; otherwise iterate quickly with one yes/no per system.
For each in-scope system, also confirm: 1-3 sentence description.
Phase 4: Capture Dependencies
For each in-scope system, ask the user (or infer from the concept):
- Which other systems must exist for this to function (hard dependencies)?
- Which systems would enrich it but are not required (soft dependencies)?
Build a dependency table. Validate:
- No cycles. If a cycle is detected, surface it: "Auth depends on Profile, Profile depends on Auth — break this with a contract or merge them."
- Foundation systems should depend only on other Foundation systems.
- Core systems may depend on Foundation.
- Supporting features may depend on Foundation and Core.
Phase 5: Prioritize Design Order
Topological sort: the design order respects dependencies (upstream first).
Within each layer, prioritize by:
- Risk — is this on the riskiest-assumption path? Higher priority.
- MVP weight — how central to the v1 promise.
- Specialist availability — if a system needs a hard-to-source specialist, schedule it earlier so blockers surface early.
Assign each system a priority bucket: P0 (must design first), P1, P2. P0 should be ≤ 5 systems.
Phase 6: Build the Index
Write design/systems-index.md:
# Systems Index
> **Generated**: <date>
> **Source concept**: `design/concept.md`
> **Total systems**: <N>
## Progress Tracker
- Total: <N>
- Designed: 0
- In review: 0
- Approved: 0
## Design Order
The order below reflects upstream-first decomposition. Run `/design-system <name>` for each, top to bottom.
### Foundation (P0)
| # | System | Layer | Priority | Status | Doc |
|---|--------|-------|----------|--------|-----|
| 1 | navigation-shell | Foundation | P0 | Not started | — |
| 2 | auth | Foundation | P0 | Not started | — |
| 3 | persistence | Foundation | P0 | Not started | — |
| ... |
### Core (P0–P1)
| ... |
### Supporting (P1–P2)
| ... |
### Monetization (P1)
| ... |
## Dependency Graph
auth
├─ persistence
├─ network-client
└─ error-reporting
profile → auth, persistence
[etc — render as ASCII tree or simple text]
## Out of v1 Scope (deferred)
- <system>: <reason — typically from concept's cut list>
## Open Mapping Questions
- <any unresolved item from the conversation>
Ask: "May I write this to design/systems-index.md?"
Phase 7: Detect Anti-Patterns
Before finishing, scan the proposed map for common issues:
- Foundation explosion: more than ~10 Foundation systems means the team is over-architecting.
- Core orphans: a Core system with no Foundation dependencies — likely missing a lower-layer dependency.
- Notifications without auth: push systems that don't depend on Auth.
- Paywall without auth: monetization needs identity.
- Single P0 with 6+ dependents: bottleneck — flag as a critical-path risk.
- No analytics in MVP: if the concept's primary metric is engagement-based, analytics must be P0.
Surface each as a callout in the index under "Open Mapping Questions" or as a warning before write.
Phase 8: Hand Off
After writing:
- Print: "Systems index written. Next:
/design-system <first P0 system> — author the first PRD."
- Update
production/session-state/active.md with the next-system pointer.
Use AskUserQuestion:
- Prompt: "Want to start designing the first system now?"
- Options:
Yes — /design-system ``Run /design-bible first (recommended if not yet done)Stop here for now
Edge Cases
- Concept implies too many systems for v1: surface the cut list. Suggest deferring 30%+ to v1.1.
- Concept does not describe a core mechanic: stop. The concept is too vague — recommend re-running
/brainstorm.
- Updating an existing index: only add new systems and update statuses; never silently delete a row. If a system is being killed, mark it
Killed and keep the row.
Quality Gates
- Every in-scope system has: name, layer, priority, dependency list, status.
- The dependency graph is acyclic.
- Foundation systems depend only on other Foundation systems.
- The next-priority system pointer is set.
- Out-of-scope list is non-empty (the concept's cut list must be reflected here).
Examples
For a "bouldering project tracker":
- Foundation: navigation, auth, local persistence (SwiftData), error reporting
- Core: project list, attempt logger, session timer
- Supporting: profile, settings, notifications (session reminders), share-image
- Monetization: deferred to v1.1 (per concept doc cut list)
- P0 design order: auth → persistence → project list → attempt logger
