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. |
Skill Graph context
Classification
- Subject:
software-architecture
- Public:
true
- Domain:
architecture/decision-records
- Scope: Writing, reviewing, and updating Architecture Decision Records — context, decision, options rejected, consequences, status, supersession, and follow-up verification. Portable across any project that records architectural decisions; principle-grounded, not repo-bound. Excludes general documentation prose (documentation), code-review findings (code-review), and choosing between frameworks before a decision exists (framework-fit-analysis).
When to use
- write an ADR for choosing Postgres views as the source of truth
- review this architecture decision record for missing consequences and rejected options
- this decision changed - should we amend the ADR or supersede it?
- extract the decision from this long architecture discussion into a durable ADR
Not for
- write a general README section explaining how this module works
- choose which framework we should use for this project
- review this PR for bugs and regressions
- design the interface contract between these two services
Related skills
- Verify with:
code-review
- Related:
framework-fit-analysis, system-interface-contracts, dependency-architecture, code-review
Keywords
ADR, architecture decision record, decision log, technical decision, decision consequences, options rejected, superseded ADR, architectural rationale, decision status
1---2name: architecture-decision-records3description: 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`). Do NOT use for write a general README section explaining how this module works. Do NOT use for choose which framework we should use for this project. Do NOT use for review this PR for bugs and regressions. Do NOT use for design the interface contract between these two services.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. |6061## Skill Graph context6263<!-- skill-graph-context:start (generated — do not edit by hand) -->6465**Classification**66- Subject: `software-architecture`67- Public: `true`68- Domain: `architecture/decision-records`69- Scope: Writing, reviewing, and updating Architecture Decision Records — context, decision, options rejected, consequences, status, supersession, and follow-up verification. Portable across any project that records architectural decisions; principle-grounded, not repo-bound. Excludes general documentation prose (documentation), code-review findings (code-review), and choosing between frameworks before a decision exists (framework-fit-analysis).7071**When to use**72- write an ADR for choosing Postgres views as the source of truth73- review this architecture decision record for missing consequences and rejected options74- this decision changed - should we amend the ADR or supersede it?75- extract the decision from this long architecture discussion into a durable ADR7677**Not for**78- write a general README section explaining how this module works79- choose which framework we should use for this project80- review this PR for bugs and regressions81- design the interface contract between these two services8283**Related skills**84- Verify with: `code-review`85- Related: `framework-fit-analysis`, `system-interface-contracts`, `dependency-architecture`, `code-review`8687**Keywords**88- `ADR`, `architecture decision record`, `decision log`, `technical decision`, `decision consequences`, `options rejected`, `superseded ADR`, `architectural rationale`, `decision status`8990<!-- skill-graph-context:end -->
jacob-balslev