Architecture Decision Records
Concept of the skill
Writing, reviewing, and updating Architecture Decision Records — context, decision, options rejected, consequences, status, supersession, and follow-up verification.
Coverage
Create and audit ADRs for significant technical choices. Covers decision context, forces, considered options, chosen decision, rejected alternatives, consequences, status, supersession, links to implementation, and follow-up verification. Use for decisions with future readers, cross-team consequences, operational cost, or hard-to-reverse effects.
Philosophy of the skill
An ADR is not a design essay. It is a durable answer to "Why did we choose this, given what we knew then?" It should preserve the tradeoff, not retroactively make the decision look inevitable.
Good ADRs are short, dated, statused, and honest about consequences. If a future agent cannot tell whether the decision still holds, the record failed.
Method
- Name the decision in one sentence.
- Capture context and forces, including constraints and non-goals.
- List serious options considered, including "do nothing" when real.
- State the decision and why it won.
- Record consequences: benefits, costs, risks, migration obligations, and reversibility.
- Set status: proposed, accepted, deprecated, or superseded.
- Link implementation surfaces and verification checks.
Status Decision Table
| Situation |
ADR action |
| Decision is still under review |
Keep status proposed; record open questions and decision date target. |
| Decision has been made and implementation is active |
Set status accepted; link implementation surfaces and verification checks. |
| Decision remains historically true but is no longer recommended |
Set status deprecated; explain the replacement direction. |
| A later decision replaces it |
Set status superseded; link the newer ADR and summarize what changed. |
| Implementation drifted but the decision still stands |
Keep status, add a follow-up section with the verification gap and owner. |
| The ADR records multiple unrelated choices |
Split into one ADR per decision before accepting it. |
Verification
Do NOT Use When
| Use instead |
When |
documentation |
You need a guide, README, tutorial, or reference page. |
framework-fit-analysis |
The task is still evaluating options before a decision. |
code-review |
The task is reviewing a diff for correctness. |
system-interface-contracts |
You need to design a contract before recording the decision. |
1---2name: architecture-decision-records-23description: Use when writing, reviewing, or updating Architecture Decision Records: context, decision, options rejected, consequences, status, supersession, and follow-up verification. Do NOT use for general documentation prose (use `documentation`), code review findings (use `code-review`), or choosing between frameworks before a decision exists (use `framework-fit-analysis`).4license: MIT5---6# Architecture Decision Records78## Concept of the skill910Writing, reviewing, and updating Architecture Decision Records — context, decision, options rejected, consequences, status, supersession, and follow-up verification.1112## Coverage1314Create and audit ADRs for significant technical choices. Covers decision context, forces, considered options, chosen decision, rejected alternatives, consequences, status, supersession, links to implementation, and follow-up verification. Use for decisions with future readers, cross-team consequences, operational cost, or hard-to-reverse effects.1516## Philosophy of the skill17An ADR is not a design essay. It is a durable answer to "Why did we choose this, given what we knew then?" It should preserve the tradeoff, not retroactively make the decision look inevitable.1819Good ADRs are short, dated, statused, and honest about consequences. If a future agent cannot tell whether the decision still holds, the record failed.2021## Method22231. Name the decision in one sentence.242. Capture context and forces, including constraints and non-goals.253. List serious options considered, including "do nothing" when real.264. State the decision and why it won.275. Record consequences: benefits, costs, risks, migration obligations, and reversibility.286. Set status: proposed, accepted, deprecated, or superseded.297. Link implementation surfaces and verification checks.3031## Status Decision Table3233| Situation | ADR action |34|---|---|35| Decision is still under review | Keep status `proposed`; record open questions and decision date target. |36| Decision has been made and implementation is active | Set status `accepted`; link implementation surfaces and verification checks. |37| Decision remains historically true but is no longer recommended | Set status `deprecated`; explain the replacement direction. |38| A later decision replaces it | Set status `superseded`; link the newer ADR and summarize what changed. |39| Implementation drifted but the decision still stands | Keep status, add a follow-up section with the verification gap and owner. |40| The ADR records multiple unrelated choices | Split into one ADR per decision before accepting it. |4142## Verification4344- [ ] The ADR records one decision, not a cluster of unrelated choices45- [ ] Rejected options are concrete and plausible46- [ ] Consequences include costs and risks, not only benefits47- [ ] Status and date are present48- [ ] Supersession links are explicit when the decision changed49- [ ] Implementation references are current or intentionally absent50- [ ] The decision can be understood without reading the whole discussion that caused it5152## Do NOT Use When5354| Use instead | When |55|---|---|56| `documentation` | You need a guide, README, tutorial, or reference page. |57| `framework-fit-analysis` | The task is still evaluating options before a decision. |58| `code-review` | The task is reviewing a diff for correctness. |59| `system-interface-contracts` | You need to design a contract before recording the decision. |
jacob-balslev