adr-opslisted

# ADR Ops An **Architecture Decision Record (ADR)** captures one architectural decision: what was decided, why, what was rejected, and what it costs. ADRs are **append-only project memory** — they exist so a future maintainer touching a subsystem can recover the *reasoning* behind its shape without archaeology through git history or chat logs. This skill encapsulates a battle-tested ADR protocol and generalizes it to **any repo**. The default location is `docs/adr/`, but every script takes `--dir` so a repo can keep records anywhere (`docs/decisions/`, `architecture/adr/`, …). --- ## When to write an ADR Write one when a change has **any** of these properties: - It **constrains future options** — a boundary, an invariant, a "we will always / never do X" rule that later work must respect. - **Multiple alternatives were seriously evaluated** and the choice is not obvious in hindsight. - The **rationale is non-obvious from the code** — the code shows *what*, the ADR preserves *why*. Write one decision per ADR. If a change bundles two separable decisions, write two. ### When NOT to write one - A bug fix, refactor, or feature that follows existing architecture without changing it — that is a commit message. - A reversible, low-stakes choice — that is a code comment. - A point-in-time event with no forward constraint (a benchmark run, an incident write-up) — that is an audit/log entry, not an ADR. > **Rule of thumb:** if someone could plausibly undo this next mo