Architecture Decision
Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
When to Use This Skill
Use this skill when:
- Making technology choices
- Evaluating architectural patterns
- Creating Architecture Decision Records
- Assessing technical debt
- Comparing design alternatives
Do NOT use this skill when:
- Writing implementation code
- Working on requirements (use requirements-analysis)
- Doing full system design (use system-design)
Core Principle
Context drives decisions. No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.
The Trade-off Triangle
Every architectural decision involves trade-offs:
| Vertex |
Maximized By |
Cost |
| Simplicity |
Monolith, sync communication, single DB |
Scalability limits |
| Flexibility |
Microservices, event-driven, plugins |
Complexity overhead |
| Performance |
Caching, denormalization, optimized code |
Maintainability |
Balance Strategies:
- Start simple, add complexity as needed
- Measure before optimizing
- Use abstractions to defer decisions
- Evolve incrementally
Quality Attributes
Performance
- Metrics: Response time (p50, p95, p99), throughput, resource utilization
- Tactics: Caching, load balancing, async processing
Scalability
- Dimensions: Horizontal, vertical, elastic
- Patterns: Stateless services, sharding, event streaming
Reliability
- Metrics: Uptime, MTBF, MTTR
- Patterns: Circuit breakers, retries, redundancy
Maintainability
- Factors: Readability, modularity, testability
- Patterns: Clean architecture, DDD, SOLID
Context-Pattern Mapping
Team Context
| Context |
Preferred Patterns |
Avoid |
| Small team |
Monolith, vertical slices, shared DB |
Microservices, complex abstractions |
| Multiple teams |
Service boundaries, API contracts |
Shared state, tight coupling |
Scale Context
| Context |
Preferred Patterns |
Reasoning |
| Startup |
Monolith first, vertical scaling |
Optimize for development speed |
| Enterprise |
Service mesh, horizontal scaling |
Optimize for operational scale |
Decision Matrix Template
| Option |
Consistency |
Flexibility |
Scalability |
Complexity |
Cost |
Total |
| Option A |
5 |
2 |
3 |
2 |
3 |
15 |
| Option B |
3 |
5 |
4 |
3 |
3 |
18 |
| Option C |
2 |
3 |
5 |
1 |
2 |
13 |
Weight factors based on context priorities.
Architecture Decision Record (ADR) Template
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded]
## Context
[What is the situation requiring a decision?]
### Requirements
- [Requirement 1]
- [Requirement 2]
### Constraints
- [Constraint 1]
- [Constraint 2]
## Decision
[What is the decision?]
### Justification
- [Reason 1]
- [Reason 2]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Drawback 1]
- [Drawback 2]
## Alternatives Considered
### [Alternative 1]
Reason rejected: [Why]
### [Alternative 2]
Reason rejected: [Why]
Architectural Refactoring Patterns
Branch by Abstraction
- Create abstraction over current implementation
- Implement new solution behind abstraction
- Switch to new implementation
- Remove old implementation
Strangler Fig
- Identify boundary
- Implement new solution for new features
- Gradually migrate old features
- Retire old system
Parallel Run
- Implement new solution
- Run both old and new
- Compare results
- Switch when confident
Technical Debt Management
Debt Categories
| Type |
Examples |
Payment Strategy |
| Design |
Missing abstractions, tight coupling |
Refactoring sprints |
| Code |
Duplication, complexity, poor naming |
Continuous cleanup |
| Test |
Missing tests, flaky tests |
Test improvement |
| Documentation |
Missing docs, outdated diagrams |
Documentation sprints |
Metrics
- Debt ratio: Debt work / Total work (target < 20%)
- Interest rate: Extra effort due to debt
- Debt ceiling: Maximum acceptable debt
Anti-Patterns
Big Ball of Mud
Symptoms: No clear structure, everything depends on everything
Remedy: Identify boundaries, extract modules, establish interfaces
Distributed Monolith
Symptoms: Services must deploy together, sync chains, shared DBs
Remedy: Merge related services, async communication, separate DBs
Golden Hammer
Symptoms: One solution for all problems, force-fitting patterns
Remedy: Learn alternatives, evaluate objectively, prototype options
Related Skills
- system-design - Full system design with ADRs
- code-review - Implementation validation
- task-decomposition - Breaking down architectural work
- requirements-analysis - Understanding constraints
1---
2name: architecture-decision
3description: "Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns. This skill should be used when the user asks about 'architecture decision', 'ADR', 'design pattern selection', 'technology choice', or needs to evaluate architectural trade-offs. Keywords: architecture, ADR, patterns, trade-offs, technical debt, quality attributes, decision record."
4license: MIT
5compatibility: Works with any project. Integrates with system-design for ADR templates.
6metadata:
7 author: jwynia
8 version: "1.0"
9 type: diagnostic
10 mode: diagnostic+evaluative
11 domain: agile-software
12---
13
14# Architecture Decision
15
16Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
17
18## When to Use This Skill
19
20Use this skill when:
21- Making technology choices
22- Evaluating architectural patterns
23- Creating Architecture Decision Records
24- Assessing technical debt
25- Comparing design alternatives
26
27Do NOT use this skill when:
28- Writing implementation code
29- Working on requirements (use requirements-analysis)
30- Doing full system design (use system-design)
31
32## Core Principle
33
34**Context drives decisions.** No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.
35
36## The Trade-off Triangle
37
38Every architectural decision involves trade-offs:
39
40| Vertex | Maximized By | Cost |
41|--------|--------------|------|
42| **Simplicity** | Monolith, sync communication, single DB | Scalability limits |
43| **Flexibility** | Microservices, event-driven, plugins | Complexity overhead |
44| **Performance** | Caching, denormalization, optimized code | Maintainability |
45
46**Balance Strategies:**
47- Start simple, add complexity as needed
48- Measure before optimizing
49- Use abstractions to defer decisions
50- Evolve incrementally
51
52## Quality Attributes
53
54### Performance
55- Metrics: Response time (p50, p95, p99), throughput, resource utilization
56- Tactics: Caching, load balancing, async processing
57
58### Scalability
59- Dimensions: Horizontal, vertical, elastic
60- Patterns: Stateless services, sharding, event streaming
61
62### Reliability
63- Metrics: Uptime, MTBF, MTTR
64- Patterns: Circuit breakers, retries, redundancy
65
66### Maintainability
67- Factors: Readability, modularity, testability
68- Patterns: Clean architecture, DDD, SOLID
69
70## Context-Pattern Mapping
71
72### Team Context
73
74| Context | Preferred Patterns | Avoid |
75|---------|-------------------|-------|
76| **Small team** | Monolith, vertical slices, shared DB | Microservices, complex abstractions |
77| **Multiple teams** | Service boundaries, API contracts | Shared state, tight coupling |
78
79### Scale Context
80
81| Context | Preferred Patterns | Reasoning |
82|---------|-------------------|-----------|
83| **Startup** | Monolith first, vertical scaling | Optimize for development speed |
84| **Enterprise** | Service mesh, horizontal scaling | Optimize for operational scale |
85
86## Decision Matrix Template
87
88| Option | Consistency | Flexibility | Scalability | Complexity | Cost | Total |
89|--------|-------------|-------------|-------------|------------|------|-------|
90| Option A | 5 | 2 | 3 | 2 | 3 | 15 |
91| Option B | 3 | 5 | 4 | 3 | 3 | 18 |
92| Option C | 2 | 3 | 5 | 1 | 2 | 13 |
93
94Weight factors based on context priorities.
95
96## Architecture Decision Record (ADR) Template
97
98```markdown
99# ADR-[NUMBER]: [TITLE]
100
101## Status
102[Proposed | Accepted | Deprecated | Superseded]
103
104## Context
105[What is the situation requiring a decision?]
106
107### Requirements
108- [Requirement 1]
109- [Requirement 2]
110
111### Constraints
112- [Constraint 1]
113- [Constraint 2]
114
115## Decision
116[What is the decision?]
117
118### Justification
119- [Reason 1]
120- [Reason 2]
121
122## Consequences
123
124### Positive
125- [Benefit 1]
126- [Benefit 2]
127
128### Negative
129- [Drawback 1]
130- [Drawback 2]
131
132## Alternatives Considered
133
134### [Alternative 1]
135Reason rejected: [Why]
136
137### [Alternative 2]
138Reason rejected: [Why]
139```
140
141## Architectural Refactoring Patterns
142
143### Branch by Abstraction
1441. Create abstraction over current implementation
1452. Implement new solution behind abstraction
1463. Switch to new implementation
1474. Remove old implementation
148
149### Strangler Fig
1501. Identify boundary
1512. Implement new solution for new features
1523. Gradually migrate old features
1534. Retire old system
154
155### Parallel Run
1561. Implement new solution
1572. Run both old and new
1583. Compare results
1594. Switch when confident
160
161## Technical Debt Management
162
163### Debt Categories
164
165| Type | Examples | Payment Strategy |
166|------|----------|------------------|
167| **Design** | Missing abstractions, tight coupling | Refactoring sprints |
168| **Code** | Duplication, complexity, poor naming | Continuous cleanup |
169| **Test** | Missing tests, flaky tests | Test improvement |
170| **Documentation** | Missing docs, outdated diagrams | Documentation sprints |
171
172### Metrics
173- **Debt ratio:** Debt work / Total work (target < 20%)
174- **Interest rate:** Extra effort due to debt
175- **Debt ceiling:** Maximum acceptable debt
176
177## Anti-Patterns
178
179### Big Ball of Mud
180**Symptoms:** No clear structure, everything depends on everything
181**Remedy:** Identify boundaries, extract modules, establish interfaces
182
183### Distributed Monolith
184**Symptoms:** Services must deploy together, sync chains, shared DBs
185**Remedy:** Merge related services, async communication, separate DBs
186
187### Golden Hammer
188**Symptoms:** One solution for all problems, force-fitting patterns
189**Remedy:** Learn alternatives, evaluate objectively, prototype options
190
191## Related Skills
192
193- **system-design** - Full system design with ADRs
194- **code-review** - Implementation validation
195- **task-decomposition** - Breaking down architectural work
196- **requirements-analysis** - Understanding constraints
aAAaqwq