Use when designing/modifying system architecture or evaluating technology choices. Enforces 7-section TodoWrite with 22+ items. Triggers: "design architecture", "system design", "architectural decision", "should we use [tech]", "compare [A] vs [B]", "add new service", "microservices", "database choice", "API design", "scale to [X] users", "infrastructure decision". If thinking ANY of these, USE THIS SKILL: "quick recommendation is fine", "obvious choice", "we already know the answer", "just need to pick one", "simple architecture question".
Use when decisions affect:
Skip for:
Threshold: If the decision could cause a 3+ month re-architecture project if wrong, use this skill.
The 7 sections are a reasoning sequence, not boxes to check:
🚨 If you wrote architecture without starting with all 7 sections: DELETE and restart. Retrofitting analysis is rationalization, not evaluation.
CREATE TodoWrite with these 7 sections (22+ items total):
| Section | Minimum Items |
|---|---|
| Scale Analysis | 4+ |
| Architectural Options | 3+ |
| Ripple Effect Analysis | 5+ |
| Failure Modes | 3+ |
| Observability | 3+ |
| Documentation | 2+ |
| Migration/Compatibility | 2+ |
Do not design, propose solutions, or implement until TodoWrite is verified.
After creating TodoWrite, verify 3 random items pass this test:
Each item must have ALL THREE:
| ❌ FAILS | ✅ PASSES |
|---|---|
| "Add monitoring" | "CloudWatch: websocket.connections.active, alert if >5% error rate via PagerDuty" |
| "Evaluate caching" | "Compare: Redis (1ms, $300/mo) vs In-memory LRU (0.1ms, $0) vs No cache (100ms)" |
| "Analyze scale" | "Current: 100K DAU, 50 req/sec. 10x: 1M users, 500 req/sec. Bottleneck: PostgreSQL connection pool" |
DO NOT PROCEED until 22+ items AND quality check passes.
NEVER design for current scale only. Before proposing any solution:
NEVER present single solution. Minimum 3 distinct options, each with:
If stakeholder suggests solution: Add as Option A, evaluate with SAME rigor as alternatives.
Changes propagate across layers. Analyze ALL:
For each mode:
| Thought | Reality |
|---|---|
| "Analysis paralysis" | This IS the analysis that prevents expensive mistakes |
| "We'll add scale/alternatives/failure modes later" | Retrofitting costs 5-10x more |
| "CTO already decided" | Still needs independent evaluation |
| "Being pragmatic not dogmatic" | These requirements ARE pragmatic |
| "Just a simple feature" | Simple becomes complex at scale |
| "We already know the solution" | Compare 3 alternatives first |
| "Keep it simple" | Simple for current scale = complex re-architecture at 10x |
| "I can add missing sections to existing work" | DELETE and restart |
To skip ANY requirement, you MUST provide ALL 4:
| Skipped | Risk | Cost |
|---|---|---|
| Scale Analysis | Re-architecture in 6-12 months | 3-6 month project, 5-10x cost |
| Alternatives | Optimize wrong dimension | 2-4 month migration |
| Failure Modes | Production incidents | $5-50K per incident |
| Ripple Effects | Broken clients, data issues | Deployment failures |
| Category | Requirements |
|---|---|
| Scale | ✓ Current + 10x projected ✓ Bottlenecks ✓ Mitigations |
| Trade-offs | ✓ 3+ options ✓ Performance/complexity/cost ✓ Rationale |
| Impact | ✓ All layers analyzed ✓ Breaking changes identified |
| Failure | ✓ Specific modes ✓ Detection ✓ Mitigation ✓ Rollback |
| Documentation | ✓ ADR ✓ Diagram updated |
If any item missing, do not proceed to implementation.