Decision record

A decision record captures one significant decision: the situation that forced it, the options on the table, what was chosen, and what follows from the choice. Michael Nygard popularized the format for software, as the architecture decision record (ADR), in a 2011 post, "Documenting Architecture Decisions", with a short template of title, status, context, decision, and consequences. Many teams add an explicit list of options considered, which this skill does.

Decision records are short, numbered, and never rewritten once accepted. When a decision changes, a new record supersedes the old one, so the history of why things look the way they do stays readable. The record's real reader is the person two years from now asking "why on earth did they do this?"

When to use it