A useful decision log records what was decided, why it was decided, who was accountable, when it took effect, what evidence supported it, and which change would cause a review. Keep each significant decision as a durable entry and supersede it with a new record instead of silently rewriting history.
Decide what belongs in the log
Record choices that affect cost, schedule, security, privacy, customer commitments, architecture, operations, staffing, policy, or work that will be difficult to reverse. Routine actions that simply follow an existing rule can stay in the task history. When uncertainty exists, create a short record; the cost of a concise entry is lower than reconstructing a consequential choice months later.
The UK government's Architectural Decision Record Framework establishes a practice for documenting decisions made during system design and development. The same record structure can be adapted to nontechnical choices without pretending that every team decision is architecture.
Capture the question and context
Give the entry a stable identifier and descriptive title. State the problem, current conditions, constraints, deadline, scope, stakeholders, and assumptions known at the time. Link to the authoritative requirement, incident, research, budget, or customer record. Avoid copying secrets or personal data into a broadly visible log.
Write the decision as a direct sentence. Name the accountable owner or decision body, contributors, approval authority when different, and the effective date. Record the entry date separately if documentation happened later. Mark the status as proposed, accepted, rejected, deferred, superseded, or retired.
Preserve options, evidence, and rationale
List the realistic options considered, including doing nothing when it was viable. For each, summarize benefits, costs, risks, dependencies, and reversibility. Identify the chosen option and explain the deciding evidence. State uncertainty honestly; do not manufacture consensus or retrofit a stronger rationale after the outcome is known.
The UK National Archives' decision-record guidance describes entries with a date, background context, the decision, and why it was chosen, with optional assumptions, constraints, evaluation criteria, alternatives, implications, and related decisions. It also recommends leaving an earlier record intact and adding a new entry when the approach changes.
Record consequences and follow-up
Describe the expected positive and negative effects, operational burden, transition work, owner, due dates, and proof needed to show implementation. Link the decision to tasks rather than turning the log into the task system. If the choice creates an exception, record its expiration, compensating control, and approver.
Add related records and note conflicts. A later reader should be able to distinguish a choice that was accepted but never implemented from one that is active in production. Link evidence of implementation, validation, or rollback without changing the original reasoning.
Add a review trigger
Choose conditions that would make the assumptions or tradeoffs worth reconsidering: a cost threshold, security incident, policy change, contract renewal, missed outcome, new technical capability, volume increase, or scheduled date. Western Australia's government decision-record introduction describes entries containing status, date, review date, context, decision, and consequences.
A review trigger is not an automatic reversal. When it occurs, assign a reviewer, compare current evidence with the original assumptions, and create a new linked record that affirms, amends, or supersedes the prior decision. Preserve both entries.
Review the log as a system
Periodically scan for proposed items without owners, accepted choices without implementation evidence, expired exceptions, overdue review dates, broken links, duplicate identifiers, and decisions contradicted by later work. Restrict edits while keeping the record discoverable to authorized readers.
A complete entry answers: what question was resolved, what circumstances mattered, which options were considered, what was chosen, who owned the choice, when it applied, what evidence supported it, what consequences followed, and what event should reopen it.
Sources
- Architectural Decision Record Framework — UK Department for Science, Innovation and Technology and Government Digital Service, Nov. 4, 2025
- Architecture Decision Records — The National Archives
- Architecture Decision Records Introduction — Government of Western Australia Office of Digital Government