How to keep a decision log your team will actually use
A simple decision log format, what to log, and the habits that keep it current, so people and AI tools can find out why things are the way they are.
A decision log is a dated list of what your team decided, why, and who owns it. To make one people actually use, keep each entry to a few fields, write it within a day of the decision, mark old decisions as replaced instead of deleting them, and keep the whole log in one place people and AI tools can search.
In my experience, most decision logs die within a few weeks. The format is rarely the problem. The habit is. This guide covers both.
What a decision log is, and what it isn't
A decision log answers one question: "Why are things the way they are?" Each entry records a single decision, the context at the time, and what changed because of it.
It is not:
Meeting notes. Notes record what was said. A log records what was decided. One meeting might produce ten pages of notes and one decision. See meeting notes are not memory.
A wiki page. Wiki pages describe how things are now and get edited over time. A log entry is fixed to a date. When the decision changes, you add a new entry.
A task tracker. Tasks are work to do. Decisions are the choices that shape that work.
The idea isn't new. Software teams have kept architecture decision records (ADRs) for years. Michael Nygard's 2011 post proposed a short format: title, context, decision, status and consequences. He also suggested writing each record "as if it is a conversation with a future developer." That framing works for any team, not just engineers.
The fields that matter
Keep it small. Every extra field makes people less likely to write an entry.
Field | What goes in it | Example |
|---|---|---|
Title | A short phrase naming the decision | Cut annual discount from 20% to 15% |
Date and owner | When it was decided, and the one person accountable | 2026-09-14, Maria (Head of Sales) |
Context | The situation and options considered, stated plainly | Annual plans were 60% of new deals; margin on them was below target. Options: keep 20%, drop to 15%, drop to 10%. |
Decision | What you will do, in active voice | We will offer 15% off annual plans for all new customers from October 1. Existing customers keep their rate until renewal. |
Status | Proposed, accepted or superseded (with a link to the replacement) | Accepted |
Consequences | What changes, good and bad | Pricing page and sales deck need updating. Expect some pushback in renewals. |
The example is made up, but the shape is real. Anyone who joins next year can read it in thirty seconds and know what happened, why, and who to ask.
What counts as a decision worth logging
You don't need to log everything. Log a decision when one or more of these is true:
It affects more than one team.
It would be expensive or awkward to reverse.
Someone is likely to ask "why did we do this?" within a year.
It reverses or replaces an earlier decision.
It sets a rule people or AI tools should follow (pricing, tone of voice, data handling, tech stack).
Skip day-to-day calls that one person makes and nobody will revisit.
How to make the habit stick
Write it within 24 hours
The context is clear the day of the decision and gone a week later. Make the decision owner responsible for the entry, and give them a day.
Say "decided" out loud in meetings
At the end of any meeting where a decision was made, someone says: "So we decided X. Maria will log it." That one sentence does more than any template.
Link, don't duplicate
The entry should link to the Slack thread, the doc or the recording where the discussion happened. The log holds the outcome. The links hold the detail.
Never delete, supersede
When a decision changes, add a new entry and mark the old one as superseded, with a link to the new one. Nygard's post makes the same point. The old entry still explains why things were done a certain way in the past, which is often exactly what someone needs to know.
Review it weekly, briefly
Five minutes in a weekly team meeting: what got logged, what's missing. Keep doing it until logging stops needing a reminder.
Where to keep it
The best place is the one your team already opens every day and can search. Common options:
A shared doc or wiki page with one section per decision. Easiest to start, harder to filter as it grows.
A database in your docs tool, with fields for status, owner and date. Easy to filter by team or status.
A folder in your code repo, one Markdown file per decision. Works well for engineering decisions and coding agents.
Whatever you pick, keep one log per team or one for the company, not one per project. Scattered logs bring back the problem you're trying to solve. Atlassian reports that 50% of knowledge workers have unknowingly worked on duplicate projects, and that 25% of the workweek goes to searching for information (Atlassian). A single searchable log helps with both. More on that in duplicate work.
Make the log useful for AI tools
A decision log is one of the most useful things you can give an AI tool. When someone asks ChatGPT, Claude or a coding agent "how should I price this deal?" or "which state library do we use?", the right answer depends on decisions the model has never seen.
Three things make a log work well for AI:
Status is always filled in. An AI tool that can't tell accepted from superseded will quote the old rule with full confidence.
One decision per entry. Short, self-contained entries are easier to retrieve and cite than a long running document.
The tools can reach it. Connect it to the assistants and agents your team uses, or point your coding agent's instruction file at it. How to brief a coding agent shows how.
FAQ
What's the difference between a decision log and an ADR?
An architecture decision record is a decision log entry for a technical choice. The format works just as well for pricing, hiring, product and policy decisions.
Who should write the entries?
The person who owns the decision. They know the context best, and making it their job makes it far more likely to get done.
How long should an entry be?
Short enough to read in a minute or two. Nygard suggested one to two pages for technical records. Most business decisions fit in a paragraph per field.
What about decisions made before we started the log?
Don't try to backfill everything. Add old decisions when someone asks about them. After a few months, the ones that matter will be in the log.
Start this week
Pick one place, copy the six fields above, and log the next decision your team makes. Then do it again next week. A decision log only works if it's current, and it only stays current if writing an entry takes less time than explaining the decision twice. We're building Shane to keep your team's decisions with their sources and status, and hand them to every teammate and AI tool that needs them. If that's a problem your team has, you can join the waitlist at tryshane.ai.