The short version
- Most decision logs record what was decided. The useful field is why the option everyone would reach for first was rejected.
- Without that field, teams re open the same decision every time a new person arrives with a reasonable suggestion.
- Six fields, fits on half a page, takes ten minutes. Anything longer does not get written.
- Log the decision when it is made, not in a review afterwards. The reasoning is already fading by the next morning.
A decision log is one of those practices everyone agrees with and few teams sustain. The usual pattern is three months of diligent entries, then a gap, then an abandoned page. The cause is almost always the format: templates that ask for background, options considered, stakeholders consulted and consequences take forty minutes, so they get postponed and then never written.
The template
| Field | One line each |
|---|---|
| Date and owner | When, and one named person accountable |
| Decision | What we are doing, in one sentence a newcomer could follow |
| The obvious option we rejected | What most people would reach for first, and why it loses |
| What would change our mind | The condition under which this should be revisited |
| Reversible? | Yes or no, and roughly what undoing it costs |
| Who was not consulted | Honest note on who might object later. Often blank. |
A filled example
Date and owner: 14 September 2026, Kofi
Decision: Customer exports run as a nightly batch, not on demand.
The obvious option we rejected: On demand exports, which is what customers ask for and what every competitor offers. Rejected because our largest three accounts have datasets big enough that an on demand export locks the reporting database for several minutes. We measured it in August. Two of those accounts would hit it daily.
What would change our mind: If we move reporting to a read replica, the objection disappears entirely and we should switch.
Reversible? Yes, about a week of work, no data migration.
Who was not consulted: Sales. They will push back, because on demand is in two competitors' pitch decks.
Read that as a new engineer in eight months. You now know not to propose on demand exports, you know the exact condition under which the answer changes, and you know who will raise it again. That is the entire purpose of the artifact.
Why the rejected option matters most
Teams do not waste time on decisions they have made. They waste time on decisions they have made and cannot defend, because the defence lived in a conversation.
The pattern is familiar. Someone new joins, looks at the nightly export, and says the obvious thing: why not do it on demand? Nobody present remembers the load measurement. The idea sounds good. Two weeks of work goes into rediscovering an answer that was known a year ago.
The rejected option field makes that impossible, and it costs one sentence at the moment of the decision, when the reasoning is still fresh and articulate. A day later it is already reconstructed rather than remembered. See why teams re argue decisions.
What to log and what to skip
Do not log everything. A log with two hundred entries is unsearchable and demoralising to maintain.
- Log it when the obvious option was rejected. This is the single best filter and it catches almost everything worth keeping.
- Log it when it is hard to reverse, even if uncontroversial at the time.
- Log it when it will surprise someone who arrives later.
- Skip it when the decision is self evident from the result. Nobody needs a record explaining why you used the standard library.
Most teams end up logging one or two decisions a week, which is sustainable. See also reversible and irreversible decisions.
Keeping it alive past month three
Logs die for two reasons: writing them is a separate task from the work, and reading them is a separate task from the question.
The first is fixed by the ten minute format and by writing at the moment of decision rather than in a weekly round up. The second is harder, because nobody browses a decision log. They hit a question, and the question does not arrive labelled with which entry answers it.
That is what StandIn is built for. The daily brief already captures what moved, what is open, what is blocked and what is next, and decisions land in it as they are made, in the owner's words. When someone asks why exports are nightly, the answer comes back from that record, with a source under it. It never guesses, and when nothing was recorded it says so and names who to ask, rather than producing a plausible sounding rationale that nobody actually gave. The log stops being a place you have to remember to visit. See how it works and documenting decisions so they stop being reopened.
Common Questions
Where should the log live?
Wherever the work lives. Engineering decisions in the repository, commercial ones in the account record. A central decision log is tidy and nobody finds it at the moment they need it.
Is this the same as an architecture decision record?
Same idea, lighter. An ADR is a good fit for a team with an engineering documentation habit. This format works for teams that have tried ADRs and stopped. See decision log and decision record compared.
Who writes the entry?
The decision owner, at the time. Delegating it to a note taker loses the reasoning, because the reasoning is the part that was in the owner's head rather than said aloud.
What about decisions that turn out to be wrong?
Leave them and add a new entry that supersedes. A log that is edited to look correct in hindsight is worthless, and the wrong decisions are the most instructive entries in it.
On your behalf. Never as you.
Every decision your team makes becomes something the next person can ask about, with the person who made it named as the source.