---
name: system-design
description: >-
  Designs scalable, reliable systems from functional and non-functional requirements.
  Produces architecture diagrams, data models, API designs, and tradeoff analysis.
  Use when building new services, designing architecture, or evaluating design alternatives.
  NOT for code-level refactoring, reviewing existing architecture, or infrastructure provisioning.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** opus
**Scope:** Requirements docs, existing system docs, API contracts, data schemas, infrastructure configs
**Off-limits:** Implementing code, deploying infrastructure, purchasing cloud resources, modifying production
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Clarify requirements before designing** — Distinguish functional from non-functional. Never assume scale. Guards against: over/under-engineered systems built on guesses.
2. **Name every tradeoff** — State what you chose, what you rejected, and why. Guards against: designs hiding unacknowledged limitations.
3. **Design the failure path first** — Define what happens when each component fails before optimizing happy path. Guards against: architectures that collapse under real failures.
4. **Deep-dive the hardest part** — The single most challenging aspect gets detailed design. Guards against: hand-waving the critical path.
## When to Use
- Designing a new service or system from scratch
- Evaluating architecture alternatives for a major feature
- System design interviews or exercises
- Producing a design document for team review
- "Design a system that does X" / "How should we architect Y?"
## When NOT to Use
- Reviewing existing architecture — use `code-architecture-review` instead
- Code-level refactoring — use `technical-debt-assessment` instead
- Infrastructure provisioning — use DevOps/infrastructure skills instead
- API documentation — use `api-documentation` instead
- Evaluating plan risks — use `risk-assessment` instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll assume standard web scale (1M users)" | Assumed scale leads to wrong engineering — ask or estimate |
| "Microservices are always the right answer" | Monoliths are correct at many scales — microservices add ops complexity |
| "I'll skip the data model, the API implies it" | Data models drive queries, indexing, scaling — must be explicit |
| "Eventual consistency is fine everywhere" | Payments, auth require strong consistency — analyze per use case |
| "I'll design happy path, add error handling later" | Failure modes shape the architecture — not an afterthought |
## Workflow
### Phase 1: Requirements Clarification
**Entry:** User has described what the system should do
**Actions:**
1. Extract functional requirements (what the system does)
2. Extract non-functional requirements (QPS, latency p50/p99, availability, durability, consistency)
3. Estimate scale: users, requests/sec, data volume, growth rate
4. Identify hard constraints: cost, technology restrictions, compliance
5. Document open questions and assumptions
**Exit:** Requirements doc with functional, non-functional, scale, constraints
### Phase 2: API and Data Model
**Entry:** Requirements documented
**Actions:**
1. Define external API (endpoints, request/response contracts)
2. Design data model: entities, relationships, access patterns
3. Identify primary query patterns and design indexes/partitioning
4. Choose consistency model per data type with justification
5. Estimate storage requirements and growth
**Exit:** API contract and data model with access patterns
### Phase 3: Architecture Design
**Entry:** API and data model defined
**Actions:**
1. Draw high-level architecture (components + data flow)
2. Design failure path for each component
3. Identify critical path and deep-dive it in detail
4. Select patterns for workload: caching, queues, search, pubsub
5. Address bottlenecks: partitioning, replication, async, CDN
**Exit:** Architecture diagram with failure modes and critical path detail
### Phase 4: Tradeoff Analysis
**Entry:** Architecture complete
**Actions:**
1. Document each decision: chosen, rejected, rationale
2. Identify what breaks first at 10x load and the scaling plan
3. Estimate infrastructure costs at current and projected scale
4. List operational complexity per architectural choice
**Exit:** Tradeoff table and scaling analysis
### Phase 5: Verification
**Entry:** All prior phases complete
**Actions:**
1. Verify all NFRs addressed (latency, availability, consistency, durability)
2. Confirm data model supports all query patterns
3. Check every component has failure mode and recovery strategy
4. Validate critical path detail is implementation-ready
5. Ensure all tradeoffs documented with rationale
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "system-design",
  "status": "completed",
  "worker": "worker-id",
  "summary": "URL shortener: 100M URLs, 10K writes/sec, 100K reads/sec. Redis cache + PostgreSQL.",
  "findings": [
    {"item": "Write-behind cache pattern", "severity": "info", "detail": "Writes to Redis, async-flush to PG. 10K w/sec, p99 <50ms. Risk: 5s data-loss window on Redis failure."},
    {"item": "Hash collision resolution", "severity": "high", "detail": "Base62 7-char: 3.5T combos. At 100M, collision <0.003%. Retry with counter suffix."},
    {"item": "Scaling bottleneck at 50x", "severity": "medium", "detail": "Single PG handles current. At 50x: partition by hash prefix. Path: read replicas first."}
  ],
  "components": ["API Gateway", "Redis Cache", "PostgreSQL", "Async Worker", "CDN"],
  "nfr_coverage": {"latency_p99": "50ms read, 80ms write", "availability": "99.95%", "consistency": "eventual (5s)", "durability": "PG WAL + daily backup"},
  "errors": [], "elapsed_seconds": 150.2
}
```
### Bad Example
```json
{"skill": "system-design", "summary": "Designed a URL shortener", "findings": [{"item": "Use Redis and PostgreSQL", "severity": "info", "detail": "Standard web architecture"}]}
```
Wrong: No scale numbers, no tradeoffs, no failure modes. "Standard web architecture" is not a design.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] NFRs unspecified and cannot be reasonably estimated
- [ ] Design requires cost decisions (infrastructure purchases)
- [ ] Requirements contain fundamental contradictions
- [ ] System handles financial transactions, PII, or health data needing compliance
- [ ] Need production metrics to make informed decisions
- [ ] Scope expands beyond original request

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] Functional and non-functional requirements documented
- [ ] API contract and data model with access patterns defined
- [ ] Architecture diagram with all components and data flow
- [ ] Every component has failure mode and recovery strategy
- [ ] Critical path deep-dived in implementation-ready detail
- [ ] All tradeoffs documented with rationale
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
