adr

Audit, write, or revise Architecture Decision Records (ADRs), including the decision of whether one is warranted. Use when an architecturally significant decision needs recording, when reviewing an ex

SKILL.md

GitHub

ADR

References:

Is one warranted?

  • Yes: architecturally significant and hard to reverse — sets precedent others will follow, locks in a dependency, shapes a public API, picks between non-trivial alternatives.
  • No: tactical implementation choice, easily reversed, personal style, framework-default behaviour. A commit message or PR description carries it better.
  • If not warranted, say so and stop. ADR sprawl makes the collection worth less.

Template

Detect, don't impose:

  1. If the repo already has ADRs (docs/adr/, doc/adr/, docs/decisions/, docs/explanation/adr/), read one and match shape.
  2. If repo-local CLAUDE.md names a template ("ADRs use MADR"), respect it.
  3. Otherwise: Nygard for a single decision; escalate to MADR only when alternatives analysis is genuinely load-bearing (3+ options worth comparing across multiple drivers). Call that case a comparison ADR.

Nygard skeleton

  • Title — # N. <imperative phrase> (e.g. "Use PostgreSQL").
  • Status — Proposed initially; user promotes to Accepted. Don't pre-mark Accepted. Later values: Accepted ADRs.
  • Context — forces in play, constraints, what made this a decision.
  • Decision — We will <do X>. Active voice.
  • Consequences — what becomes easier and harder; positive, negative, neutral.

MADR

Use the upstream template at https://adr.github.io/madr/; don't re-derive it here. Sections that earn their weight: Decision Drivers, Considered Options (with pros/cons), Decision Outcome.

Decompose and verify

Comparison ADRs only; a single-decision Nygard record skips it.

A comparison ADR that starts from an inherited conclusion reverse-justifies it with abstract drivers ("cross-surface leverage", "maintenance burden") and never examines the facts that decide it. Run this interview with the user before any Context, driver, or outcome prose exists:

  1. Options — name the concrete candidates under comparison.
  2. Requirements — get the targets from the user, enumerated. Not from memory, not inferred from the options.
  3. Option × requirement — for each pair, state the fact and where it came from. Reachability, feasibility, and cost decide most tool choices; verify those pairs first. Anything assumed, recalled, or unchecked is a blocker: search it before continuing, and never write the Decision Outcome over an open one.
  4. Inherited answer — name the option that arrived pre-chosen, if any. Check whether each driver tests that option or flatters it; a driver only the pre-chosen option satisfies is there to justify it.
  5. Draft — every Decision Driver cites a verified fact from step
    1. Cut any driver that can't; don't hedge it.

Accepted ADRs

An Accepted ADR is fixed. Its only edit is a Status transition:

  • Superseded by NNNN — the decision changed. Write the new ADR through Procedure; set this Status on its predecessor in the same change.
  • Deprecated — the decision no longer applies and nothing replaces it, such as a dropped technology. This is the whole change.

Its facts record the state at decision time. A fact that has since changed routes to a new ADR or a transition.

Location and filename

  • Default docs/adr/ for new repos. Match existing layout if present.
  • Filename: NNNN-kebab-title.md, NNNN is the next 4-digit sequence (0001, 0002, ...).
  • If no ADRs exist yet, scaffold 0000-record-architecture-decisions.md first (the meta-ADR establishing the practice itself).

Procedure

  1. A request about an Accepted ADR ("update ADR N to reflect X"): pick its transition from Accepted ADRs before opening the file. Deprecated stops here.
  2. Decide warranted vs. not. If not, stop.
  3. Detect template and location from existing ADRs or repo CLAUDE.md.
  4. For a comparison ADR, run Decompose and verify before drafting.
  5. Compute next sequence number. If first ADR, scaffold the meta-ADR too.
  6. Surface chosen template, location, and a one-line decision summary before drafting full content. Apply after agreement.
  7. Default Status to Proposed. The team promotes it after the decision is actually made.