jacob-balslev/skill-graph / marketplace/skills/architecture-decision-records
architecture-decision-records
VerifiedUse 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.
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
- The ADR records one decision, not a cluster of unrelated choices
- Rejected options are concrete and plausible
- Consequences include costs and risks, not only benefits
- Status and date are present
- Supersession links are explicit when the decision changed
- Implementation references are current or intentionally absent
- The decision can be understood without reading the whole discussion that caused it
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |