Recording decisions

REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).

Overview

Two formats, by weight: a full ADR for a decision with architecture-level consequences; a decision log entry for the running stream of smaller choices. Both are append-only: an accepted decision is immutable; new context is a new entry that supersedes the old one.

When to invoke, and not

Invoke when a choice has been made and needs recording, when someone asks "write down why we did this", or when an existing decision is superseded. Do NOT invoke for a decision still being argued (that is writing-design-docs; its Why & What box becomes the ADR once accepted).

Also invoke on the signals that an unrecorded decision is passing by: "we decided X instead of Y", "let's just go with", a trade-off resolved in a PR comment or chat thread, or a rationale someone has now explained twice. Each is a decision living in a non-durable place; offer to record it.

Record the decision before citing it. A chat session is not a durable source. Put the dated substance in the log, quote the decider where wording matters, commit the entry, then cite it. Record the smallest complete decision, not a transcript.

ADR

Nygard format. One decision per ADR.