ADR Writer

Record why one design direction was chosen over alternatives, under what constraints, and with what consequences. An ADR is not a mini-RFC or an execution log.

Discovery

Read related decisions and requirements first with govctl adr show <ADR-ID> and govctl search <topic>; add --history only when superseded history matters. Use govctl <resource> --help for current syntax.

Hard Stops

• Do not accept, reject, or supersede an ADR here; hand that to spec or gov.
• RFCs own obligations, ADRs own design rationale, and Work Items own execution scope. Do not create behavior, validation, lifecycle, storage, or compatibility obligations in ADR prose, and do not record task scope, progress, commands, or validation output.
• Stop if the governing requirement or the decision itself is unclear.

Writing Order

1. Context: the problem, constraints, and decision drivers.
2. Alternatives actually considered, with only the pros and cons that influenced the outcome. Never pad to a quota: one real rejected option beats three fabricated ones, and when only one viable direction exists, say so in a sentence.
3. Mark chosen and rejected alternatives and why each rejected one lost.
4. Decision: commit clearly to what is decided, as the conclusion of that comparison.
5. Consequences: benefits, costs, and mitigations, not only benefits.

For a historical backfill, separate recovered evidence from inference and say so when alternatives cannot be recovered.

Decide Only What Must Be Decided Now

An ADR written before implementation has little evidence about low-level design, yet implementing agents treat everything it states as settled. Record the direction, boundaries, and constraints that are costly to reverse or that other work depends on. For each sub-choice, ask whether deciding it during coding would lose anything; if not, leave it out, or name it as deferred to implementation with any constraint it must respect.

Data layouts, helper decomposition, algorithms, error-handling mechanics, and step-by-step procedures rarely belong in an ADR written before code exists. Record such a choice after implementation has produced the evidence. Language-specific structure belongs only when it is central to the decision.

Keep It Short

A typical ADR is a few dozen lines. Cut background the reader already has, alternatives nobody seriously considered, and pros and cons that did not matter. Bloat is a defect: it hides the decision.

Normative keywords quoted from an RFC do not make the ADR authoritative. Rewrite accidental obligation lists as rationale, or move the missing contract to its RFC.

Projection Ownership

Per [[RFC-0000:C-ADR-PROJECTION-OWNERSHIP]]:

Do not write Context, Decision, Consequences, or Alternatives Considered headings into content fields, and do not restate alternatives' statuses, pros, cons, or rejection reasons in prose.

Before Handoff

• every alternative was really considered, and an uncontested decision says so;
• the decision leaves choices that coding can settle better to implementation;
• consequences include real costs;
• references connect the decision to its governing RFCs, and configured project tags are applied;
• govctl check passes; and
• adr-reviewer has no unresolved critical finding.