system-design

name	system-design
description	Use when designing, architecting, or planning a new system from requirements or ideas - transforms concepts into navigable design catalog using EventStorming methodology, Mermaid diagrams, and progressive elaboration through 5 phases (Requirements, Big Picture, Processes, Data/Flows, Integration)

System Design Through EventStorming

Overview

Transform requirements into navigable design catalogs using EventStorming methodology and Mermaid diagrams.

Core principle: Progressive elaboration through event-driven thinking, producing token-efficient visual artifacts in standardized catalog structure.

Announce at start: "I'm using the system-design skill to create a design catalog for your system."

When to Use

Use when:

• User wants to design a new system
• Requirements exist but design doesn't
• Need structured thinking before implementation
• Team needs shared visual artifacts

Don't use when:

• Adding features to existing system (consider brainstorming instead)
• Implementation already started
• User wants code, not design

Quick Reference

Phase	Key Activities	Output Files
1. Requirements	Ask questions, identify actors/constraints	requirements.md
2. Big Picture	EventStorming timeline with events/commands	big-picture.mmd
3. Processes	Zoom into critical processes, add aggregates	process-{name}.mmd
4. Data & Flows	ERD, state charts, sequences	erd.mmd, state-{entity}.mmd, sequence-{flow}.mmd
5. Integration	Generate catalog README	README.md

The Iron Laws

Law 1: ASK QUESTIONS - No Assumptions

NEVER make "industry-standard assumptions" without asking the user first.

• Ask about actors, constraints, scale, budget, timeline
• Use AskUserQuestion tool for architectural choices
• Mark unclear areas as hotspots instead of assuming

Bad:

❌ "I'll assume standard PostgreSQL for data storage"
❌ "Proceeding with industry-standard assumptions"
❌ "I'll design for moderate scale (10K users)"

Good:

✅ "What database are you currently using?" (AskUserQuestion with options)
✅ "What scale are you targeting?" (AskUserQuestion: 100 users / 10K / 100K+)
✅ "Budget constraints for infrastructure?" (Ask directly)

Law 2: MERMAID ONLY - No ASCII Diagrams

All diagrams MUST use Mermaid format. NO exceptions.

• No ASCII art
• No text-based diagrams
• No "version control friendly" excuses for avoiding Mermaid

Bad:

❌ ASCII art entity relationships
❌ Text-based flowcharts
❌ "I'll create ASCII diagrams because they're universal"

Good:

✅ Mermaid ER diagrams
✅ Mermaid flowcharts
✅ Mermaid sequence diagrams
✅ Mermaid state charts

Law 3: EVENTSTORMING - Event-Driven Thinking

Use EventStorming methodology for Phases 2-3. Required.

• Identify domain events (what happens in the system)
• Add commands (what triggers events)
• Add actors (who initiates)
• Add systems (external integrations)
• Mark hotspots (unclear/risky areas)

Bad:

❌ "Using traditional waterfall analysis"
❌ "Creating use cases and functional specs"
❌ "Based on proven patterns" (without events)

Good:

✅ "Let's identify key business events" (EventStorming)
✅ "What triggers each event?" (Commands)
✅ "What data changes when this event happens?" (Aggregates)

Law 4: CATALOG STRUCTURE - Standardized Organization

All artifacts go into docs/design-catalog/ with specific structure.

docs/design-catalog/
  README.md              # Navigation hub
  requirements.md
  big-picture.mmd
  processes/
    process-{name}.mmd
  data/
    erd.mmd
    state-{entity}.mmd
  flows/
    sequence-{flow}.mmd

No random file names. No mixed concerns.

Law 5: DESIGN NOT IMPLEMENTATION

Stay at design abstraction. NO implementation details in design phase.

Forbidden in design artifacts:

• ❌ Database schemas (SQL, migrations)
• ❌ Deployment guides (Docker, Kubernetes)
• ❌ CI/CD pipelines
• ❌ Specific technology choices (unless user specified)
• ❌ Implementation timelines (16-week plans)
• ❌ Team structure recommendations
• ❌ Code examples (API endpoints, controllers, services, functions)
• ❌ Configuration files (YAML, JSON, ENV)

Allowed:

• ✅ Entity relationships (conceptual)
• ✅ State transitions (conceptual)
• ✅ Event flows (conceptual)
• ✅ Integration points (generic)
• ✅ Hotspots for technical decisions

Law 6: TOKEN EFFICIENCY - Diagrams Over Prose

Prefer Mermaid diagrams over lengthy text descriptions.

Token targets by project complexity:

• Simple (single service, 5-10 entities): < 10K tokens
• Medium (2-3 services, 10-20 entities): < 20K tokens
• Complex (multiple services, 20+ entities): < 35K tokens

If exceeding targets, check:

• Are you writing prose that diagrams could show?
• Are you repeating information across files?
• Are you including implementation details?

Bad:

❌ 4,000 lines of documentation
❌ Verbose explanations of every decision
❌ Repeating information across files
❌ "This is complex so 50K tokens is reasonable"

Good:

✅ Mermaid diagram with annotations
✅ Cross-reference: "See big-picture.mmd for event flow"
✅ Tables for entity attributes
✅ Minimal prose, maximum visual clarity

The 5 Phases

REQUIRED: Use TodoWrite to track phase progress.

Copy this checklist:

System Design Progress:
- [ ] Phase 1: Requirements (actors, constraints, goals identified)
- [ ] Phase 2: Big Picture (EventStorming timeline created)
- [ ] Phase 3: Processes (Critical processes detailed)
- [ ] Phase 4: Data & Flows (ERD, state charts, sequences created)
- [ ] Phase 5: Integration (Catalog assembled, next steps planned)

Phase 1: Requirements Understanding

Goal: Understand context before designing

Activities:

1. Ask questions ONE at a time (following brainstorming pattern)
2. Use AskUserQuestion for architectural choices with trade-offs
3. Identify: business goals, constraints, key actors, success criteria

Questions to ask:

• "What problem does this system solve?"
• "Who are the primary users/actors?"
• "What are the critical constraints?" (performance, scale, budget, timeline)
• "How do you define success?"
• "What systems need to integrate?"

Output: Create docs/design-catalog/requirements.md

Validation: Present requirements summary, ask: "Does this capture the scope?"

Phase 2: EventStorming Big Picture

Goal: Understand business process through events

Announce: "Let's explore the business process through EventStorming."

Activities:

1. Ask: "What are the key business events that happen in this system?"
2. Build timeline collaboratively (add events as user describes)
3. Ask: "Who triggers each event? What commands cause them?"
4. Add actors and commands
5. Ask: "Are there external systems involved?"
6. Add external systems
7. Mark hotspots for unclear areas (DON'T assume, MARK AS HOTSPOT)

EventStorming Color Conventions (Mermaid):

flowchart LR
    %% Style definitions
    classDef event fill:#ff9800,stroke:#e65100,color:#000
    classDef command fill:#2196f3,stroke:#0d47a1,color:#fff
    classDef actor fill:#ffeb3b,stroke:#f57f17,color:#000
    classDef system fill:#9c27b0,stroke:#4a148c,color:#fff
    classDef aggregate fill:#4caf50,stroke:#1b5e20,color:#fff
    classDef hotspot fill:#f44336,stroke:#b71c1c,color:#fff

    Actor[Customer]:::actor
    Cmd1[Place Order]:::command
    Evt1[Order Placed]:::event
    Agg1[Order]:::aggregate
    Sys1[Payment Gateway]:::system
    Hot1[? Refund policy unclear]:::hotspot

    Actor --> Cmd1
    Cmd1 --> Evt1
    Evt1 --> Agg1
    Agg1 --> Sys1
    Evt1 -.question.- Hot1

Output: Create docs/design-catalog/big-picture.mmd

Validation: Present diagram, ask: "Does this capture the high-level flow?"

Phase 3: Process EventStorming

Goal: Detail specific processes from big picture

Activities:

1. Identify 2-4 critical processes to detail (not more)
2. For each process:
   • Ask: "Let's detail the {process name} process"
   • Ask: "What aggregates (data entities) are involved?"
   • Ask: "What state changes happen at each event?"
   • Build detailed process diagram with color coding

Criteria for "critical" processes:

• Touches multiple aggregates
• Has complex business rules
• High business value or risk
• User specifically mentioned as important

Output: Create docs/design-catalog/processes/process-{name}.mmd (one per process)

Validation: Review each process diagram before moving to next

Phase 4: System Design Artifacts

Goal: Model data, state, and interactions

4.1 Entity-Relationship Diagram

• Extract entities from process diagrams
• Ask: "What are the relationships between these entities?"
• Define attributes (but NOT database schema)
• Use Mermaid ER diagram syntax

Output: docs/design-catalog/data/erd.mmd

4.2 State Charts

• Identify entities with complex lifecycles
• Ask: "Which entities have important state transitions?"
• Map states, transitions, triggers
• Annotate data changes per transition
• Use Mermaid stateDiagram-v2
• Limit: 2-4 entities max (only entities with complex lifecycles)

Output: docs/design-catalog/data/state-{entity}.mmd (one per entity)

4.3 Sequence Diagrams

• Ask: "Which flows need detailed interaction modeling?"
• Select critical/complex flows
• Map actor/system interactions
• Show success AND error paths
• Use Mermaid sequenceDiagram
• Limit: 2-4 flows max (only critical/complex flows)

Output: docs/design-catalog/flows/sequence-{flow}.mmd (one per flow)

Don't diagram everything - focus on what adds clarity.

Validation: Present all artifacts, ask: "Does this design feel complete?"

Phase 5: Integration & Next Steps

Goal: Assemble catalog and plan next actions

Activities:

1. Generate catalog README with:
   • Project overview
   • Links to all artifacts
   • EMBED ALL DIAGRAMS (copy full Mermaid content from each .mmd file)
   • Navigation to processes, states, flows
   • All diagrams must be visible in README for easy preview
2. Present complete design catalog
3. Ask: "Ready to proceed with implementation planning?"

CRITICAL: The README must include the FULL Mermaid diagram content inline, not just links. Copy the entire contents of each .mmd file into the README's mermaid code blocks. This enables preview without opening individual files.

Options:

• Standalone design: Stop here, design complete
• Implementation planning: Use writing-plans skill
• Pumped-design mapping: (If backend + pumped-fn) Map to pumped-fn catalog

Output: docs/design-catalog/README.md (with all diagrams embedded)

Iterative Refinement

User can jump back to earlier phases when insights emerge.

Support non-linear progression:

• "Let's refine requirements" → Return to Phase 1, update downstream
• "Big picture is missing X" → Return to Phase 2, revise
• "Process needs more detail" → Return to Phase 3, expand
• "Data model has issues" → Return to Phase 4, adjust

Flexibility principle: Design is discovery - support iteration

Mermaid Templates

See templates/ directory for:

• big-picture-template.mmd - EventStorming timeline
• process-template.mmd - Process EventStorming
• erd-template.mmd - Entity-Relationship
• state-template.mmd - State chart
• sequence-template.mmd - Sequence diagram
• requirements-template.md - Requirements structure
• catalog-readme-template.md - Catalog README

Common Rationalizations (DON'T DO THESE)

Excuse	Reality
"Industry-standard assumptions are fine"	Ask questions to understand THIS project
"ASCII diagrams are version control friendly"	Mermaid is required - renders AND version controls
"Comprehensive documentation is better"	Token-efficient diagrams beat verbose prose
"Traditional approach works"	EventStorming reveals events you'd miss otherwise
"Production-ready blueprint needed"	Design phase stays conceptual, not implementation
"All aspects should be covered"	Focus on design artifacts, defer implementation
"Database schema helps developers"	Too early - stay at entity/relationship level
"Technology choices are obvious"	Mark as hotspot or ask user, don't assume

Red Flags - STOP and Self-Check

If you catch yourself doing ANY of these, you're violating the skill:

• Making assumptions without asking
• Creating ASCII diagrams
• Skipping EventStorming
• Writing SQL schemas
• Creating deployment guides
• Making technology choices without user input
• Using > 35,000 tokens for complex design (see Law 6 targets)
• Not using TodoWrite for phases
• Creating README with only links to diagrams (must embed full content)

All of these mean: Stop, re-read the skill, start over correctly.

Integration with Other Skills

Brainstorming

• Phase 1 (Requirements) borrows question patterns
• Use AskUserQuestion tool similarly
• One question at a time

Writing-Plans

• Optional handoff after Phase 5
• Design catalog provides context for implementation tasks

Pumped-Design

• Optional mapping for backend systems
• Translate catalog to pumped-fn structure
• ERD → resources, Processes → flows

Success Criteria

Design is successful when:

• User engaged through questions (not assumptions)
• All diagrams in Mermaid format
• EventStorming methodology followed
• Catalog structure created correctly
• Token usage efficient (< 15K for typical project)
• Hotspots marked instead of assumed
• Stayed at design level (no SQL, deployment, etc.)
• Phases tracked with TodoWrite

Example: Minimal E-commerce Big Picture

flowchart LR
    %% Styles
    classDef event fill:#ff9800,stroke:#e65100,color:#000
    classDef command fill:#2196f3,stroke:#0d47a1,color:#fff
    classDef actor fill:#ffeb3b,stroke:#f57f17,color:#000
    classDef system fill:#9c27b0,stroke:#4a148c,color:#fff
    classDef hotspot fill:#f44336,stroke:#b71c1c,color:#fff

    %% Actors
    Customer[Customer]:::actor
    Seller[Seller]:::actor

    %% Commands & Events
    Browse[Browse Products]:::command
    Add[Add to Cart]:::command
    Checkout[Checkout]:::command

    ProductViewed[Product Viewed]:::event
    ItemAdded[Item Added to Cart]:::event
    OrderPlaced[Order Placed]:::event
    PaymentProcessed[Payment Processed]:::event

    %% Systems
    PaymentGW[Payment Gateway]:::system

    %% Hotspots
    Hot1[? Refund policy unclear]:::hotspot
    Hot2[? Inventory sync timing?]:::hotspot

    %% Flow
    Customer --> Browse
    Browse --> ProductViewed
    Customer --> Add
    Add --> ItemAdded
    Customer --> Checkout
    Checkout --> OrderPlaced
    OrderPlaced --> PaymentProcessed
    PaymentProcessed --> PaymentGW
    OrderPlaced -.question.- Hot1
    ItemAdded -.question.- Hot2

This is minimal - real design would be more detailed. But shows the pattern.

Summary

System design through EventStorming:

1. Ask questions (no assumptions)
2. Use Mermaid (no ASCII)
3. Follow EventStorming (event-driven thinking)
4. Create catalog structure (standardized)
5. Stay at design level (no implementation)
6. Be token-efficient (diagrams over prose)
7. Track with TodoWrite (phase discipline)

Result: Navigable design catalog that feeds into implementation planning.