cloudthinker-ai Architecture Decision Record Skill
Create ADR {{ adr_number }}: {{ adr_title }} for {{ decision_scope }}.
Workflow
Step 1 — ADR Header
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ADR {{ adr_number }}: {{ adr_title }}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: PROPOSED / ACCEPTED / DEPRECATED / SUPERSEDED
Date: [auto-populated]
Scope: {{ decision_scope }}
Decision makers: [list names/roles]
Consulted: [list stakeholders consulted]
Informed: [list people to be informed]
Step 2 — Context & Problem Statement
CONTEXT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROBLEM STATEMENT:
[2-3 sentences describing the problem or question that needs a decision.
What is the current situation? Why does a decision need to be made now?]
DECISION DRIVERS:
- [Driver 1: e.g., "Must support 10x traffic growth in 12 months"]
- [Driver 2: e.g., "Team has limited experience with technology X"]
- [Driver 3: e.g., "Must comply with SOC2 requirements"]
- [Driver 4: e.g., "Budget constraint of $X/month"]
CONSTRAINTS:
- [Constraint 1: e.g., "Must be compatible with existing CI/CD pipeline"]
- [Constraint 2: e.g., "Cannot require more than 2 weeks of migration effort"]
ASSUMPTIONS:
- [Assumption 1: e.g., "Traffic will grow 20% MoM"]
- [Assumption 2: e.g., "Team will have 2 engineers available for implementation"]
Step 3 — Considered Options
OPTIONS CONSIDERED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPTION A: [Name]
Description: [1-2 sentences]
Pros:
+ [advantage]
+ [advantage]
Cons:
- [disadvantage]
- [disadvantage]
Cost: [effort, money, time]
Risk: LOW / MEDIUM / HIGH
OPTION B: [Name]
Description: [1-2 sentences]
Pros:
+ [advantage]
+ [advantage]
Cons:
- [disadvantage]
- [disadvantage]
Cost: [effort, money, time]
Risk: LOW / MEDIUM / HIGH
OPTION C: [Name]
Description: [1-2 sentences]
Pros:
+ [advantage]
+ [advantage]
Cons:
- [disadvantage]
- [disadvantage]
Cost: [effort, money, time]
Risk: LOW / MEDIUM / HIGH
Step 4 — Decision Matrix
DECISION MATRIX
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Criteria | Weight | Option A | Option B | Option C |
|----------|--------|----------|----------|----------|
| [criteria 1] | [1-5] | [1-5] | [1-5] | [1-5] |
| [criteria 2] | [1-5] | [1-5] | [1-5] | [1-5] |
| [criteria 3] | [1-5] | [1-5] | [1-5] | [1-5] |
| [criteria 4] | [1-5] | [1-5] | [1-5] | [1-5] |
| [criteria 5] | [1-5] | [1-5] | [1-5] | [1-5] |
| **Weighted Total** | | **___** | **___** | **___** |
Common criteria: scalability, maintainability, cost, team expertise,
time to implement, operational complexity, security, vendor lock-in
Step 5 — Decision Outcome
DECISION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHOSEN OPTION: [Option X — Name]
RATIONALE:
[2-3 sentences explaining why this option was selected over alternatives.
Reference the decision drivers and how this option best satisfies them.]
WHAT THIS MEANS:
We will: [concrete action]
We will not: [explicitly rejected approach]
We accept: [known trade-offs]
Step 6 — Consequences
CONSEQUENCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
POSITIVE:
+ [benefit this decision brings]
+ [benefit]
+ [benefit]
NEGATIVE:
- [trade-off or cost accepted]
- [trade-off]
RISKS:
- [risk]: [mitigation strategy]
- [risk]: [mitigation strategy]
FOLLOW-UP DECISIONS NEEDED:
- [decision that will need to be made as a result]
- [decision]
Step 7 — Implementation Plan
IMPLEMENTATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Phase | Task | Owner | Timeline |
|-------|------|-------|----------|
| 1 | [task] | [name] | [dates] |
| 2 | [task] | [name] | [dates] |
| 3 | [task] | [name] | [dates] |
VALIDATION CRITERIA:
[ ] [How we will know the decision was correct]
[ ] [Metric or milestone to evaluate]
REVIEW DATE: [when to revisit this decision]
Step 8 — Related ADRs
RELATED DECISIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Supersedes: [ADR-XXX (if replacing a previous decision)]
Related to: [ADR-YYY, ADR-ZZZ]
Superseded by: [none — will be updated if this ADR is replaced]
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|---|---|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |
Output Format
Produce an ADR document with:
- Header (number, title, status, date, decision makers)
- Context with problem statement, drivers, and constraints
- Options with pros/cons analysis and decision matrix
- Decision with rationale and chosen option
- Consequences (positive, negative, risks, follow-ups)
- Implementation plan with timeline and validation criteria