Architecture Decision Review & ADR Generator
Purpose
Use this skill to:
- Evaluate proposed architectural choices in a structured way.
- Make trade-offs explicit and reviewable.
- Generate clear, maintainable Architecture Decision Records (ADRs).
- Prevent “mystery decisions” and institutional memory loss.
When to Use
- New services, major components, or infrastructure patterns.
- Significant changes to data models, consistency guarantees, or integration patterns.
- New technology adoption (frameworks, databases, messaging systems).
- Reversals of prior decisions (deprecating or replacing an approach).
Decision Review Workflow
Clarify the problem and context
- What exact problem is this decision trying to solve?
- What constraints exist: latency, throughput, reliability, cost, compliance, team expertise, deadlines?
- What is explicitly out of scope for this decision?
Enumerate meaningful alternatives
- List at least 2–3 viable options, including “do nothing” or “minimal change”.
- For each, summarize how it would address the problem.
Assess options against quality attributes
For each option, evaluate:
- Reliability and availability
- Performance and scalability
- Security and compliance
- Operability (monitoring, debugging, deployment)
- Developer experience and velocity
- Cost (short-term and long-term)
- Risk and reversibility
Identify risks and unknowns
- What assumptions are you making?
- What proof (spikes, benchmarks, prior art) would de-risk the choice?
- What is the blast radius if the decision is wrong?
Make the decision explicit
- Choose one option (or combination).
- Capture rationale: why this over the others?
- Capture expected lifetime: is this a tactical or strategic decision?
Define follow-ups and guardrails
- What needs to be monitored to validate the decision?
- What metrics or events would trigger reconsideration?
- What migration or rollback path exists?
ADR Template
When generating an ADR, use this structure:
ADR-XXX: <Short, imperative title>
Status
Proposed | Accepted | Deprecated | Superseded by ADR-YYY
Context
Problem we are solving.
Background and existing constraints.
Relevant historical context or prior ADRs.
Decision
The choice we are making.
Scope and boundaries.
Key assumptions.
Consequences
Positive
Benefits and why they matter.
Negative / Risks
Costs, trade-offs, and potential pitfalls.
New failure modes introduced.
Alternatives Considered
Option A: summary + why rejected.
Option B: summary + why rejected.
“Do nothing”: impact of not changing.
Implementation Notes
High-level integration points and interfaces.
Migration or rollout strategy.
Monitoring, observability, and testing considerations.
Follow-ups
Experiments, spikes, or measurements to run.
Triggers for re-evaluating this decision.
Review Heuristics
Use these questions to sanity-check decisions:
- Is this as simple as possible, but not simpler, for current requirements?
- Is the decision reversible? If not, are we appropriately cautious?
- Are we solving today’s problem or an imagined future one?
- Will future engineers understand and respect this decision just from the ADR?
Examples of Good Prompts
- “Use the architecture decision review framework to evaluate these two options and generate an ADR.”
- “Given this design doc, produce an ADR that captures the main decision and trade-offs.”
- “Compare microservice vs. modular monolith for this case using the framework, then recommend one and draft an ADR.”
1---2name: architecture-decision-review3description: Framework for evaluating architectural decisions and generating high-quality Architecture Decision Records (ADRs).4---5
6# Architecture Decision Review & ADR Generator
7
8## Purpose
9
10Use this skill to:
11
12- Evaluate proposed architectural choices in a structured way.
13- Make trade-offs explicit and reviewable.
14- Generate clear, maintainable Architecture Decision Records (ADRs).
15- Prevent “mystery decisions” and institutional memory loss.
16
17---
18
19## When to Use
20
21- New services, major components, or infrastructure patterns.
22- Significant changes to data models, consistency guarantees, or integration patterns.
23- New technology adoption (frameworks, databases, messaging systems).
24- Reversals of prior decisions (deprecating or replacing an approach).
25
26---
27
28## Decision Review Workflow
29
301. **Clarify the problem and context**
31 - What exact problem is this decision trying to solve?
32 - What constraints exist: latency, throughput, reliability, cost, compliance, team expertise, deadlines?
33 - What is explicitly **out of scope** for this decision?
34
352. **Enumerate meaningful alternatives**
36 - List at least 2–3 viable options, including “do nothing” or “minimal change”.
37 - For each, summarize how it would address the problem.
38
393. **Assess options against quality attributes**
40 For each option, evaluate:
41
42 - Reliability and availability
43 - Performance and scalability
44 - Security and compliance
45 - Operability (monitoring, debugging, deployment)
46 - Developer experience and velocity
47 - Cost (short-term and long-term)
48 - Risk and reversibility
49
504. **Identify risks and unknowns**
51 - What assumptions are you making?
52 - What proof (spikes, benchmarks, prior art) would de-risk the choice?
53 - What is the blast radius if the decision is wrong?
54
555. **Make the decision explicit**
56 - Choose one option (or combination).
57 - Capture rationale: why this over the others?
58 - Capture expected lifetime: is this a tactical or strategic decision?
59
606. **Define follow-ups and guardrails**
61 - What needs to be monitored to validate the decision?
62 - What metrics or events would trigger reconsideration?
63 - What migration or rollback path exists?
64
65---
66
67## ADR Template
68
69When generating an ADR, use this structure:
70
71```text
72ADR-XXX: <Short, imperative title>
73Status
74Proposed | Accepted | Deprecated | Superseded by ADR-YYY
75
76Context
77Problem we are solving.
78
79Background and existing constraints.
80
81Relevant historical context or prior ADRs.
82
83Decision
84The choice we are making.
85
86Scope and boundaries.
87
88Key assumptions.
89
90Consequences
91Positive
92Benefits and why they matter.
93
94Negative / Risks
95Costs, trade-offs, and potential pitfalls.
96
97New failure modes introduced.
98
99Alternatives Considered
100Option A: summary + why rejected.
101
102Option B: summary + why rejected.
103
104“Do nothing”: impact of not changing.
105
106Implementation Notes
107High-level integration points and interfaces.
108
109Migration or rollout strategy.
110
111Monitoring, observability, and testing considerations.
112
113Follow-ups
114Experiments, spikes, or measurements to run.
115
116Triggers for re-evaluating this decision.
117```
118
119## Review Heuristics
120
121Use these questions to sanity-check decisions:
122
123- Is this **as simple as possible**, but not simpler, for current requirements?
124- Is the decision **reversible**? If not, are we appropriately cautious?
125- Are we solving today’s problem or an imagined future one?
126- Will future engineers understand and respect this decision just from the ADR?
127
128---
129
130## Examples of Good Prompts
131
132- “Use the architecture decision review framework to evaluate these two options and generate an ADR.”
133- “Given this design doc, produce an ADR that captures the main decision and trade-offs.”
134- “Compare microservice vs. modular monolith for this case using the framework, then recommend one and draft an ADR.”
majiayu000