Architecture decision records

Skill jacob-balslev/skills/skills/software-architecture/architecture-decision-records

Public Agent Skills library exported from skill-graph. Install: npx skills add jacob-balslev/skills

Install

npx -y skills add jacob-balslev/skills --skill architecture-decision-records

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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`).

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

10.9 KB, as published. Nobody here has run it

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.