docs-adr — Decision memory the next session can load

Degree of freedom: MIXED — T1 is the priority. What to record [HIGH freedom]; format, supersede-not-edit, and present-backfill-first [LOW freedom — run exactly].

Install and maintain the repo's decision memory. Code shows what was decided; nothing shows why, or what was rejected — so every new agent session is free to "improve" its way back to an alternative you already ruled out. Re-litigated decisions are the slowest form of drift. An ADR makes the decision durable and its reversal deliberate.

This skill vs neighbors

How to reason

1. Observe — the decision, the rejected alternative, who already tried to reverse it
2. Interpret — would a fresh agent "improve" back to the rejected option?
3. Classify — ADR / not-an-ADR (linter already enforces, routine impl)
4. Severity — load-bearing unusual choice first

Worked example

Observe: agent PR re-proposes Zustand; repo uses React context for session by choice; no ADR. Interpret: the rejection is oral memory — the next session will retry. Classify: ADR — stack choice with a rejected alternative. Write: "We use React context for session. Rejected Zustand: duplicate store vs server session." Present the backfill list before writing files.

Phase 0 — Set up the system (once per repo) [LOW freedom — INDEX.md + statuses]

• docs/adr/NNNN-short-title.md, numbered sequentially, plus docs/adr/INDEX.md — one line per ADR (NNNN | title | status | one-line decision). The index is the agent-facing surface: small enough to load every session.
• Reference the index from agent rules: "Before proposing a change to architecture, dependencies, conventions, or data models, read docs/adr/INDEX.md; do not contradict an Accepted ADR without flagging it explicitly to the user."
• Statuses: Proposed → Accepted → Superseded by NNNN / Deprecated. Never edit an Accepted ADR's decision — supersede it with a new one that links back. History is the point.

Phase 1 — The format (one page, hard cap) [LOW freedom — this shape]

# NNNN. <Decision as a verb phrase>
Status: Accepted            Date: YYYY-MM-DD
## Context
2–5 sentences: the forces. What problem, what constraints.
## Decision
1–3 sentences, imperative: "We use X for Y."
## Rejected alternatives
The load-bearing section for agents. Each alternative: one line — what
it was, WHY it lost. This is what stops re-proposal.
## Consequences
2–4 sentences: what this commits us to, what it makes harder, when to
revisit.

No restating documentation, no tutorials, no aspirational essays. If it exceeds a page it is two decisions or it is documentation (route to docs-writer). "We tried it and it failed because…" is the highest-value content — failure memory is exactly what a fresh session lacks.

Phase 2 — What gets an ADR (and what does not) [HIGH freedom]

Write one for any decision an agent could plausibly reverse while "helping":

• Stack and dependency choices (and the ones rejected), including versions pinned for a reason.
• Architecture and layering (enhance-arch-boundaries model is ADR #1 material).
• Conventions with non-obvious rationale.
• Product / scope decisions that shape code ("no user accounts in v1 — deliberately").
• Reversals of past attempts — the "we already tried that" archive.

Not ADRs: routine implementation choices, anything the linter / gate already enforces mechanically, TODOs, meeting notes. Over-recording kills the system as surely as under-recording.

Phase 3 — Backfill mode (existing repo) [LOW freedom — confirm list before writing]

Mine implicit decisions before they are lost:

• From the code: unusual choices that look wrong but are load-bearing (the thing every new agent "fixes" first).
• From git history / PR descriptions: reversions and migrations.
• From the user, one focused pass: "What has an agent (or a past you) tried to change that must stay, and why?" Write those first.

Cap the backfill at decisions that still bind (typically 5–15). This is memory, not archaeology for its own sake.

Phase 4 — Keep it alive [LOW freedom — supersede, do not edit Accepted]

• New ADR in the same PR as the decision it records.
• /handoff / completion: any decision that meets the Phase-2 bar gets filed before closure (enhance-agent-guardrails can install the reminder).
• When an agent's proposal contradicts an Accepted ADR: surface, cite, ask — do not silently comply or silently override. Changing course produces a superseding ADR, on purpose, by the human.
• Periodic sweep (fits workflow-housekeep): statuses current, index matches files, superseded chains intact.

Definition of Done

• docs/adr/ + INDEX.md exist; numbering and statuses in place
• Agent rules load the index each session and forbid silent contradiction of Accepted ADRs
• Format enforced: one page, rejected-alternatives section present, supersede-not-edit
• Scope rules recorded (what does / does not get an ADR)
• Backfill done for still-binding decisions, "things agents keep trying to change" first
• Same-PR rule and handoff hook wired
• Index verified against files (no dangling numbers, no unindexed ADRs)

Self-critique before writing ADRs [LOW freedom — do not skip]

1. Backfill list shown first — decisions are theirs; recording is yours
2. Rejected alternatives filled — an ADR without them will not stop re-proposal
3. One page — two decisions or it's docs (docs-writer)
4. Never edit Accepted — supersede
5. Not everything — linter-enforced and TODOs stay out

Output format

1. System files — the directory, INDEX.md, agent-rule text added
2. Backfilled ADRs — each one page, rejected-alternatives filled
3. Lifecycle wiring — same-PR rule, handoff hook, housekeep sweep item

Present the backfill list for confirmation before writing the ADRs — the decisions are theirs; the recording is yours.