Short answer
A decision log template records six things per decision: the date, the question, the options considered, what was chosen, who chose it, and why. Keep one markdown file per decision in a shared folder, numbered so it sorts itself, and mark reversed decisions superseded instead of deleting them, so the reasoning stays readable for people and AI assistants.
A decision log template needs six things per decision: the date, the question, the options that were on the table, what was chosen, who chose it, and why. Keep one markdown file per decision rather than one row per decision, because the reasons are the part people come back for, and a spreadsheet cell is where reasons get cut to fit.
The templates that rank for this are spreadsheets, and a spreadsheet is fine for listing decisions. It is bad at the job a decision log is really for, which is stopping the same argument coming back six months later when the person who won it has left. In 2026 that argument often comes back from an AI assistant, which proposes the option the team already rejected because it never saw the log. I write this from Baalda, where a team keeps its notes as plain markdown files in one shared vault and each person's assistant reads and writes them over MCP. So the template below is plain markdown that works in any editor, and the rest of the post is about where to keep it so that both the team and its assistants read it before they reopen a settled question.
What goes in a decision log template?
One file per decision, named with a number and a short noun phrase, so the folder sorts itself and the filename says what was decided:
Decisions/
0001-postgres-over-firestore.md
0002-annual-pricing-only.md
0003-weekly-release-train.mdInside each file, copy this:
# 0003 Weekly release train
Status: accepted
Date: 2026-11-14
Decided by: Sara (owner), Imran, Leila
Supersedes: none
### Question
How often do we ship to customers?
### Options we considered
- Continuous deploys from main
- A weekly release every Tuesday
- Fortnightly releases with a freeze
### Decision
A weekly release every Tuesday. Hotfixes can go out any day.
### Why
Support needs one predictable day to warn customers. Continuous deploys
broke the changelog twice in October. Fortnightly made fixes wait too long.
### Consequences
QA testing moves to Monday. The changelog is written per release, not per merge.
### Revisit when
We have automated end-to-end tests covering checkout.Two fields here do more work than the rest. Options we considered is what stops the reopening: when someone suggests continuous deploys next spring, the answer is already written, with the reason it lost. Revisit when turns "we decided this forever" into a condition anyone can check, so a decision can be reopened on purpose instead of by accident.
Keep each record short. Michael Nygard, who named this format, wrote that "The whole document should be one or two pages long." Most of ours are a third of a page.
Spreadsheet or one file per decision?
Both are real options, and they suit different logs.
| One row per decision | One file per decision | |
|---|---|---|
| Good for | Many small project calls, sorted and filtered | Fewer decisions that carry real reasoning |
| The reasoning | Squeezed into a cell | As long as it needs to be |
| Linking | A URL in a column | Links between decisions and to the notes they came from |
| Reversals | Edit the row, lose the old answer | A new file, the old one marked superseded |
| What an AI assistant can read | Usually nothing, the sheet sits in someone's Drive | Plain text, if it can reach the folder |
If you are a project manager tracking two hundred scope calls on one project, a spreadsheet is the better tool, and Smartsheet, Excel and the rest have free templates that do it well. If the log is meant to explain to next year's team why things are the way they are, one file per decision wins, because that explanation does not fit in a cell.
Where does the decision record format come from?
From software architecture. In November 2011 Michael Nygard published "Documenting Architecture Decisions", which proposed short records with five parts: a title, the context ("the forces at play, including technological, political, social, and project local"), the decision, a status, and the consequences. He kept them in the repository as Markdown files, numbered: "Numbers will not be reused." Those records are what engineers now call ADRs, architecture decision records, and the template above is the same idea with the options and the owner spelled out for non-engineers.
A popular variant is MADR, Markdown Architectural Decision Records, whose 4.0.0 release came out on 17 September 2024. If your log is only for engineering decisions about code, MADR in the code repository is a good default and you can stop reading here.
Why should a decision log live where your AI assistant can read it?
Because the assistant is now one of the people most likely to reopen a decision. Ask Claude or Cursor to speed up the release process and, without the log, a reasonable suggestion is continuous deploys, the exact option the team rejected in October. It is not being careless. The reason it lost lives in a meeting, a Slack thread, or a sheet the assistant cannot open.
In Baalda the log is a Decisions/ folder in the team's shared vault: real .md files on every member's disk, edited live by several people at once. Each person connects their assistant to the vault over MCP with their own token, and from then on the log is something it reads and writes, not something someone pastes in.
Two tools do most of the work. Before proposing a change, the assistant calls search_notes, which runs a semantic and keyword search over everything that person can access, finds 0003-weekly-release-train.md, and reads it with read_note. Its suggestion then starts from the decision instead of contradicting it. And when a meeting does settle something, the assistant files the record with create_note, a vault-relative path such as Decisions/0004-move-support-to-email.md, and the template filled in from the conversation. A person reads it, fixes what the assistant got wrong, and the record is done while the reasons are still fresh.
This is the habit that keeps a log alive. Logs die because writing the record is a chore that happens after the meeting, if at all. When the record is drafted in the same conversation where the decision was made, the chore shrinks to a review. The same reasoning is behind writing a knowledge transfer document while the person is still there, not on their last day.
What happens when a decision is reversed?
You do not edit the old answer away. Write a new record, point it at the old one with Supersedes: 0003, and change the old record's status to superseded by 0007. Nygard's rule was the same: "If a decision is reversed, we will keep the old one around, but mark it as superseded." The old file still explains why the team thought weekly releases were right, which is exactly what someone needs when they wonder whether to go back.
With an assistant doing the edit, there is one failure to guard against: two writers changing the same record at once. Baalda's edit_note changes one exact piece of text, here the Status: line, without resending the whole note, and it accepts an expectedRevision taken from read_note. If anyone changed the record after the assistant read it, the write is refused and nothing is written, so the assistant has to read the record again before it marks anything superseded. A person editing in the app does not need this, because simultaneous edits there merge live. Either way, the note's earlier versions are listed in its version history, so you can see when a status changed.
Because each status is plain text, finding every reversed decision is a full-text search for superseded, by a person or by the assistant.
Who should be able to read which decisions?
Most decisions should be readable by everyone, which is the point of logging them. A few should not: a pricing change before it is announced, a hiring decision, a vendor dispute. In a shared spreadsheet that means a second spreadsheet. In Baalda it means a second folder, say Decisions/Leads/, with access set once on the folder, and every record inside inherits it.
The assistant follows the same line. Its MCP token acts as the person who created it, so search_notes never returns a record that person could not open. Someone outside the leads group can ask their assistant about pricing and it will find the public decisions and nothing else. Per-file permissions covers how that access model works. If you are setting up the rest of a team's notes around the log, the startup knowledge base puts the decision log next to the four other pages a small team needs.
Where does this not help?
No tool makes people write decisions down. An assistant that drafts the record lowers the cost, but someone still has to say "let's log that" at the end of the meeting, and someone has to read the draft. If nobody owns the habit, the folder will be empty in March whatever app it lives in.
A folder of notes is also not a project tracker. If what you need is two hundred small decisions sorted by owner and due date, with filters, a spreadsheet or your project tool does that better than a folder of files does.
Baalda has no approval step. Status is a line of text that anyone with edit access can change, so if decisions need formal sign-off, that process lives outside the note, and per-folder edit access is the only lever for who can change a record.
And if your decisions are about code, the code repository is still the best home for them, as Nygard had it. Baalda earns its place for the decisions that are not about code, such as pricing, process, hiring and vendors, and for teams where the people and assistants who need to read the log are not all in the repository.