name: architecture-discipline
description: 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".
Architecture Discipline
When to Use
Use when decisions affect:
- Data models or schema changes
- Service boundaries or new services
- Deployment topology or infrastructure
- Scale characteristics (10x growth implications)
- Technology stack choices
- API contracts or external integrations
Skip for:
- Parameter tweaks or configuration changes
- UI/styling changes
- Localization or copy changes
- Bug fixes within existing architecture
- Adding fields to existing models (unless schema migration)
Threshold: If the decision could cause a 3+ month re-architecture project if wrong, use this skill.
CRITICAL: This Is Reasoning Discipline, Not a Checklist
The 7 sections are a reasoning sequence, not boxes to check:
- Alternatives BEFORE choosing
- Scale requirements BEFORE design
- Failure modes built in, not bolted on
🚨 If you wrote architecture without starting with all 7 sections: DELETE and restart. Retrofitting analysis is rationalization, not evaluation.
MANDATORY FIRST STEP
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.
Verification Checkpoint
After creating TodoWrite, verify 3 random items pass this test:
Each item must have ALL THREE:
- ✓ Concrete numbers/thresholds ("100K users", "$500/mo", "P95 < 500ms")
- ✓ Specific tools/technologies ("PostgreSQL", "Redis", "CloudWatch")
- ✓ Measurable outcome ("handles 1M req/sec", "costs $X at 10x")
| ❌ 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.
Section Requirements
1. Scale Analysis (4+ items)
NEVER design for current scale only. Before proposing any solution:
- Current scale: Users (DAU/MAU), requests/sec, data volume, read/write ratio
- 10x scale: What numbers at 10x? When expected?
- Bottlenecks: What breaks at 10x? (DB connections, API limits, memory)
- Mitigation: Specific solution for each bottleneck
2. Architectural Options (3+ items)
NEVER present single solution. Minimum 3 distinct options, each with:
- Performance: Latency (P50/P95/P99), throughput, scale limit
- Complexity: LOC estimate, services involved, operational burden
- Cost: Infrastructure ($X/mo current, $Y/mo at 10x), development (engineer-weeks)
- Trade-offs: Specific advantages (✅) and disadvantages (❌)
If stakeholder suggests solution: Add as Option A, evaluate with SAME rigor as alternatives.
3. Ripple Effect Analysis (5+ items)
Changes propagate across layers. Analyze ALL:
- Data layer: Schema changes, migrations, indexes, query performance
- Services: Which need updates? API contracts changed?
- API: Breaking changes? Version bump? Backward compatibility?
- Clients: Mobile updates? Web UI changes?
- Operations: Deployment changes? New monitoring? Cost changes?
4. Failure Modes (3+ items)
For each mode:
- Scenario: [Component] fails because [reason]
- Detection: How we know (metrics drop, error rate spike)
- Impact: What breaks (user features, data integrity)
- Mitigation: Circuit breaker, fallback, redundancy
5. Observability (3+ items)
- Metrics: Specific (latency P95, error rate %, throughput)
- Alerts: Conditions (error rate > 5%, latency P95 > 500ms)
- Dashboards: Key visualizations
6. Documentation (2+ items)
- ADR: Chosen option, rejected alternatives, trade-offs, constraints
- Diagram: New components, data flows, failure paths
7. Migration/Compatibility (2+ items)
- Backward compatibility: Old clients work? API versioning?
- Migration path: Phased rollout, feature flags, rollback procedure
Red Flags - STOP When You Think:
| 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 |
Override Requirements
To skip ANY requirement, you MUST provide ALL 4:
- Specific retrofit date (not "later")
- Budget allocated (engineer-weeks)
- Risk acceptance signed by decision maker
- Interim mitigation plan
| 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 |
Verification Before Complete
| 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.
1---2name: architecture-discipline3description: Use when designing/modifying system architecture or evaluating technology choices. Enforces 7-section TodoWrite with 22+ items. Triggers: "design architecture", "system design", "architectural decisio4---5
6---
7name: architecture-discipline
8description: 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".
9---
10
11# Architecture Discipline
12
13## When to Use
14
15**Use when decisions affect:**
16- Data models or schema changes
17- Service boundaries or new services
18- Deployment topology or infrastructure
19- Scale characteristics (10x growth implications)
20- Technology stack choices
21- API contracts or external integrations
22
23**Skip for:**
24- Parameter tweaks or configuration changes
25- UI/styling changes
26- Localization or copy changes
27- Bug fixes within existing architecture
28- Adding fields to existing models (unless schema migration)
29
30**Threshold:** If the decision could cause a 3+ month re-architecture project if wrong, use this skill.
31
32## CRITICAL: This Is Reasoning Discipline, Not a Checklist
33
34The 7 sections are a **reasoning sequence**, not boxes to check:
35- Alternatives BEFORE choosing
36- Scale requirements BEFORE design
37- Failure modes built in, not bolted on
38
39🚨 **If you wrote architecture without starting with all 7 sections:** DELETE and restart. Retrofitting analysis is rationalization, not evaluation.
40
41---
42
43## MANDATORY FIRST STEP
44
45**CREATE TodoWrite** with these 7 sections (22+ items total):
46
47| Section | Minimum Items |
48|---------|---------------|
49| Scale Analysis | 4+ |
50| Architectural Options | 3+ |
51| Ripple Effect Analysis | 5+ |
52| Failure Modes | 3+ |
53| Observability | 3+ |
54| Documentation | 2+ |
55| Migration/Compatibility | 2+ |
56
57**Do not design, propose solutions, or implement until TodoWrite is verified.**
58
59---
60
61## Verification Checkpoint
62
63After creating TodoWrite, verify 3 random items pass this test:
64
65**Each item must have ALL THREE:**
66- ✓ Concrete numbers/thresholds ("100K users", "$500/mo", "P95 < 500ms")
67- ✓ Specific tools/technologies ("PostgreSQL", "Redis", "CloudWatch")
68- ✓ Measurable outcome ("handles 1M req/sec", "costs $X at 10x")
69
70| ❌ FAILS | ✅ PASSES |
71|----------|-----------|
72| "Add monitoring" | "CloudWatch: `websocket.connections.active`, alert if >5% error rate via PagerDuty" |
73| "Evaluate caching" | "Compare: Redis (1ms, $300/mo) vs In-memory LRU (0.1ms, $0) vs No cache (100ms)" |
74| "Analyze scale" | "Current: 100K DAU, 50 req/sec. 10x: 1M users, 500 req/sec. Bottleneck: PostgreSQL connection pool" |
75
76**DO NOT PROCEED until 22+ items AND quality check passes.**
77
78---
79
80## Section Requirements
81
82### 1. Scale Analysis (4+ items)
83
84**NEVER design for current scale only.** Before proposing any solution:
85- Current scale: Users (DAU/MAU), requests/sec, data volume, read/write ratio
86- 10x scale: What numbers at 10x? When expected?
87- Bottlenecks: What breaks at 10x? (DB connections, API limits, memory)
88- Mitigation: Specific solution for each bottleneck
89
90### 2. Architectural Options (3+ items)
91
92**NEVER present single solution.** Minimum 3 distinct options, each with:
93- Performance: Latency (P50/P95/P99), throughput, scale limit
94- Complexity: LOC estimate, services involved, operational burden
95- Cost: Infrastructure ($X/mo current, $Y/mo at 10x), development (engineer-weeks)
96- Trade-offs: Specific advantages (✅) and disadvantages (❌)
97
98**If stakeholder suggests solution:** Add as Option A, evaluate with SAME rigor as alternatives.
99
100### 3. Ripple Effect Analysis (5+ items)
101
102Changes propagate across layers. Analyze ALL:
103- Data layer: Schema changes, migrations, indexes, query performance
104- Services: Which need updates? API contracts changed?
105- API: Breaking changes? Version bump? Backward compatibility?
106- Clients: Mobile updates? Web UI changes?
107- Operations: Deployment changes? New monitoring? Cost changes?
108
109### 4. Failure Modes (3+ items)
110
111For each mode:
112- Scenario: [Component] fails because [reason]
113- Detection: How we know (metrics drop, error rate spike)
114- Impact: What breaks (user features, data integrity)
115- Mitigation: Circuit breaker, fallback, redundancy
116
117### 5. Observability (3+ items)
118
119- Metrics: Specific (latency P95, error rate %, throughput)
120- Alerts: Conditions (error rate > 5%, latency P95 > 500ms)
121- Dashboards: Key visualizations
122
123### 6. Documentation (2+ items)
124
125- ADR: Chosen option, rejected alternatives, trade-offs, constraints
126- Diagram: New components, data flows, failure paths
127
128### 7. Migration/Compatibility (2+ items)
129
130- Backward compatibility: Old clients work? API versioning?
131- Migration path: Phased rollout, feature flags, rollback procedure
132
133---
134
135## Red Flags - STOP When You Think:
136
137| Thought | Reality |
138|---------|---------|
139| "Analysis paralysis" | This IS the analysis that prevents expensive mistakes |
140| "We'll add scale/alternatives/failure modes later" | Retrofitting costs 5-10x more |
141| "CTO already decided" | Still needs independent evaluation |
142| "Being pragmatic not dogmatic" | These requirements ARE pragmatic |
143| "Just a simple feature" | Simple becomes complex at scale |
144| "We already know the solution" | Compare 3 alternatives first |
145| "Keep it simple" | Simple for current scale = complex re-architecture at 10x |
146| "I can add missing sections to existing work" | DELETE and restart |
147
148---
149
150## Override Requirements
151
152To skip ANY requirement, you MUST provide ALL 4:
1531. Specific retrofit date (not "later")
1542. Budget allocated (engineer-weeks)
1553. Risk acceptance signed by decision maker
1564. Interim mitigation plan
157
158| Skipped | Risk | Cost |
159|---------|------|------|
160| Scale Analysis | Re-architecture in 6-12 months | 3-6 month project, 5-10x cost |
161| Alternatives | Optimize wrong dimension | 2-4 month migration |
162| Failure Modes | Production incidents | $5-50K per incident |
163| Ripple Effects | Broken clients, data issues | Deployment failures |
164
165---
166
167## Verification Before Complete
168
169| Category | Requirements |
170|----------|-------------|
171| Scale | ✓ Current + 10x projected ✓ Bottlenecks ✓ Mitigations |
172| Trade-offs | ✓ 3+ options ✓ Performance/complexity/cost ✓ Rationale |
173| Impact | ✓ All layers analyzed ✓ Breaking changes identified |
174| Failure | ✓ Specific modes ✓ Detection ✓ Mitigation ✓ Rollback |
175| Documentation | ✓ ADR ✓ Diagram updated |
176
177**If any item missing, do not proceed to implementation.**
majiayu000