Decision log template

Published 21 October 2026

A decision log is a dated list of the decisions a project has made — what was decided, why, by whom, and which requirements it changed — so that nobody has to remember them, and nobody reopens a settled question by accident. Below are what to record, a template, a worked example, how to keep the log, how it differs from an ADR, a RAID log and a change log, and versions for Excel, Confluence and Jira.

most of these disputes aren’t really about what was agreed. They’re about who can produce the clearest record of it fastest.

— r/projectmanagement, 2026

Michael Nygard, in his 2011 post on architecture decision records, put the problem this way: “One of the hardest things to track during the life of a project is the motivation behind certain decisions” (Documenting Architecture Decisions, 2011). Without a log, the reason lives in a meeting or a chat — “slack threads that explain a decision but good luck finding them”, as one commenter puts it (r/ProductManagement, 2026).

What to record in a decision log

Decision log template

Copy it into a document, a wiki page or a spreadsheet; one block per decision. Square brackets are yours to fill in.

DECISION LOG
Project:  [name]
Kept by:  [name, role]

D-[n]  [the decision, in one sentence]
Date:        [   ]
Decided by:  [name, role]
Consulted:   [names, roles]
Why:         [the reason]
Options:     [alternatives turned down]
Affects:     [requirement IDs], version
             [x.y]
Source:      [meeting, email, CR, ADR]
Status:      proposed / accepted /
             superseded by D-[n]
Revisit:     [date or condition]

Decision log example

The customer portal from the other templates. The finance lead and the head of sales are the client’s; the tech lead is the supplier’s.

Each entry points somewhere else for the detail: D-3 and D-8 to their change requests and the impact analysis behind D-8, D-4 to its architecture decision record in the technical specification template, D-1 and D-2 to the requirements review of draft 0.9. The log is the one place that lists them all in order.

D-1 is not deleted. In June, someone who remembers “one reminder, for open invoices” can see that it was the rule, that it changed, when, and why.

How to keep a decision log

1. Keep one log per project, where the client can read it too. One consultant lists, among the records kept on every project, “A shared decision log recording what decisions were made and who on the client side made them.” (Hacker News, 2025).
2. Log it the same day, and send it back. One commenter’s routine: “After EVERY meeting I send out an email with decisions and requirements to the entire team to ensure I have captured all decisions correctly.” (r/businessanalysis, 2024). A decision someone disagrees with is better found that afternoon than at acceptance.
3. Write the decision, not the discussion. One sentence, specific enough to act on: “Google sign-in for new customers only”, not “discussed sign-in options”.
4. Name one person who decided — someone who may decide it. A decision by “the team” or “the meeting” has nobody to ask later.
5. Link it to what it changes. The requirement IDs and the version. A decision that changes agreed scope is also a change request, with its own sign-off.
6. Never edit an accepted decision; supersede it. Nygard’s rule for architecture decisions works for every kind: “If a decision is reversed, we will keep the old one around, but mark it as superseded. (It’s still relevant to know that it was the decision, but is no longer the decision.)”
7. Look at it on a schedule. Proposed decisions waiting too long, and revisit dates that have passed, are the ones that cause surprises.

Decision log vs ADR vs RAID log vs change log

Decision log vs ADR: an ADR is one decision, written at length, usually about architecture; “The collection of ADRs created and maintained in a project constitute its decision log”, in the words of the ADR community site, which adds that ADR usage “can be extended to design and other decisions” (adr.github.io). Most project decisions — a priority, a scope call, an answer to an open question — need a line in the log, not a document. The technical specification template has an ADR template.

Decision log vs change log: every approved change request is a decision, but not every decision is a change: D-5 settles an open question, and D-4 is how to build what was already agreed.

Decision log in Excel

One row per decision:

ID,Date,Decision,Why,Options,Decided by,Consulted,Affects,Version,Source,Status,Superseded by,Revisit

Keep the sheet in one place everyone can open, freeze the header row, and filter by Status to see what is current. Do not overwrite a row when a decision changes: add a new one, and put its ID in the old row’s “Superseded by”.

Decision log in Confluence and Jira

Confluence offers a decision template built on DACI — “Driver, Approver, Contributors, and Informed” — with “a single approver who ultimately makes the call” (Atlassian). It suits a large decision that needs its own page. For the log itself, one page with a table like the example above is enough, with a link from each row to the page or the change request behind it.

In Jira, a decision can be an issue of its own type, linked to the stories and requirements it affects. That keeps the link from decision to work, but the reason and the superseded status still have to be written down — a closed issue does not say whether the decision still holds.

Decision logs and AI coding agents

An AI coding agent applies whatever decisions it is given, current or not. One developer: “I kept tons of markdown docs and decision docs. Now those things are just causing problems because they got stale.” (Hacker News, 2026). Another:

The decisions are what rots silently: “we tried A, it broke, don’t go back.” Nothing in the repo changes when that call gets reversed, so nothing flags it

— r/ClaudeAI, 2026

Someone building tooling for this names the hard part: “it’s knowing which decision is still current. […] if a call got reversed six months ago, a fuzzy index will happily re-inject the old one” (Hacker News, 2026). Folders of decision records are no guarantee either: “they always end up as this forgotten folder nobody reads” (dev.to, 2026).

The status column is what helps here. An agent, or a new team member, reading D-1 alone would build one reminder for open invoices only; reading D-1 marked “superseded by D-7” would not.

Where Specroot fits

This is the problem Specroot works on: decisions recorded with the requirements and the version they changed, so a superseded decision shows as superseded wherever the requirement is read. Specroot for agencies and consultancies.