recording-decisions

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. Show more Installs 1.0K Repository riekelt/technical-writer GitHub Stars 20 First Seen 7 days ago Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Pass