Decision log template: what to record, what to skip

A decision log answers one question months later: why did we do it that way, and what did we know at the time? The value is almost entirely in the second half. A log that records the decision without the reasoning and the alternatives is a list of facts you could get from the code, the contract or the calendar. Six fields, one row per decision, appended and never edited. The threshold for logging is simple: log it if reversing it would cost more than a day, or if a new person would ask why.

The template, then an example

A spreadsheet, a table in a document, or a folder of short files — the format matters far less than whether anyone writes in it on the day.

The six fields

Date | Decision | Why | Alternatives considered | Decider | Revisit when. That is the whole schema. Resist adding a seventh column: every field you add lowers the chance a busy person fills the row in at all, and a thin log that exists beats a thorough one that does not.

Why — the field that carries the value

One or two sentences on the reasoning as it stood that day, including the constraint that forced it. Chose the managed service because we had no one to run it and a launch date six weeks out tells a future reader something that "chose the managed service" never will.

Alternatives — the field everyone skips

Considered [x], rejected because [reason]. This is what stops the same option being re-proposed every six months by someone who was not there. It also honestly records when an option was not considered, which is useful information about the decision rather than an embarrassment.

Revisit when

Revisit when [condition], or by [date]. A condition beats a date: "revisit if we pass 10,000 accounts" is checkable, "revisit in Q2" is a reminder everyone snoozes. Many decisions never need revisiting and the field reads "no" — that is a legitimate answer and worth writing.

Worked example

2026-09-16 | Ship the library on the existing static host rather than a CMS | No editor besides us; every page is generated and committed, so a CMS adds a system without removing work | Considered a headless CMS, rejected because it puts the content behind a login and an API at exactly the moment we want it crawlable | Eng lead | Revisit if a non-engineer needs to publish weekly

Superseding a decision

Never edit a row. Add a new one: Supersedes row [n]. What changed: [what we learned]. The pair of rows is the valuable artifact — it shows what you believed, what happened, and how long it took to find out. Editing the original destroys exactly the thing the log exists to preserve.

What not to log

Reversible choices, anything with an obvious answer, and preferences. If the log fills with things nobody will ever look up, people stop reading it and then stop writing it. You can always start logging more. Restoring confidence in a log people have learned to ignore is much harder.

Where it should live

Next to the work, not in a separate wiki nobody opens. A file in the repository, a tab in the project spreadsheet, a pinned page in the project channel. The single strongest predictor of whether a decision log survives is whether writing a row takes under a minute from where you already are.

Questions

What is a decision log?

An append-only record of decisions with the reasoning and the alternatives considered at the time. Its purpose is to answer "why did we do it that way" months later, when everyone who was in the room has a different memory.

What should a decision log include?

Date, the decision, why including the constraint that forced it, the alternatives and why they were rejected, the decider, and when to revisit. Six fields. More than that and people stop filling it in.

Which decisions should be logged?

Anything that would cost more than about a day to reverse, or that a new joiner would ask about. Reversible or obvious choices are noise, and noise is what kills a log.

Should you edit a decision log entry?

No. Add a new row that supersedes the old one and states what changed. The two rows together show how your understanding developed, which is more useful than either row alone.

Where should a decision log live?

As close to the work as possible — the repository, the project spreadsheet, a pinned channel page. If adding a row takes more than a minute from where someone already is, it will not happen on a busy week.

Is a decision log the same as meeting minutes?

No. Minutes record a meeting; a decision log records a decision regardless of where it happened, and many decisions are not made in meetings at all. They complement each other and neither replaces the other.

How do you get a team to actually use a decision log?

Write the row during the meeting where the decision happened, not afterwards from memory, and keep the log where the work already is. Both failures are logistical rather than cultural, and both are fixable in an afternoon.

The practical failure of decision logs is that the reasoning is clear in the room and gone by the evening, so the row gets written from memory a week later and the "why" field ends up as a restatement of the decision. Writing the row during the meeting, or from the record of it, is the difference.