Skip to content
Skills Library
Programming · Analysis

map-systems

/map-systems

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.

Licence
MIT
Last repository change
15.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. 1. Parse Arguments
  2. 2. Phase 1: Read Concept (Required Context)
  3. 3. Phase 2: Systems Enumeration (Collaborative)
  4. 4. Phase 3: Dependency Mapping (Collaborative)
  5. 5. Phase 4: Priority Assignment (Collaborative)
  6. 6. Phase 5: Create Systems Index (Write)
  7. 7. Phase 6: Design Individual Systems (Handoff to /design-system)
  8. 8. Phase 7: Suggest Next Steps
  9. Collaborative Protocol
  10. Protocol
Original SKILL.md headings · 303 lines, 1,722 words
SKILL.md preview
---
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 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]`

Versions

The database has no other skills named map-systems.

Database snapshot: 13.11.2026 · package version 864e5bc7b170 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90system-design
    Design systems, services, and architectures. Trigger with "design a system for", "how should we architect", "system design for", "what's the right architecture for", or when the user needs help with API design, data modeling, or service boundaries.
  • 100architecture
    Applies software and systems architecture discipline. Invoked when an engineer or architect is designing a new system, defining service or bounded-context boundaries, choosing a technology stack, producing a C4 diagram, writing an Architecture Decision Record (ADR), evaluating…
  • 85okhp3-mermaid-architecture
    System and solution architecture diagrams in Mermaid for technical audiences - C4 model (Context/Container/Component/Code), architecture-beta cloud/infrastructure diagrams, block diagrams, packet/protocol diagrams, service topology, and integration flows. Use when the user wants…
  • 100architecture-design
    Full-stack system architecture skill for designing C4 diagrams, API contracts, sequence diagrams, deployment topologies, and ADRs. Use when designing new systems, choosing tech stacks, defining service boundaries, or producing architecture documentation before implementation starts.
  • 100c4-model
    Generate C4 architecture documentation at any level using specialized agents (Code, Component, Container, Context). Use this skill whenever the user wants to document system architecture with the C4 model, create architecture diagrams, document code structure, define component…
  • 90mcaf-architecture-overview
    Create or refresh docs/Architecture.md as a concise map of real modules, boundaries, contracts, slices, and entry points. Use for onboarding or architecture documentation changes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.