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, and 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; the 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 of those 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 and quote the decider where wording matters, then commit the entry before citing it. Record the smallest complete decision, not a transcript.

ADR

Nygard format. One decision per ADR.