Decision log: the record of why, not just what

Strip everything else away and a decision log is a list of decisions you do not edit. You add to it. When a decision is replaced, you write a new entry and mark the old one superseded, and you leave the old one where it is.

Michael Nygard put the reason for this better than anyone since, writing about architecture decisions in 2011: a superseded record is still relevant, because it is still worth knowing that it was the decision and is no longer the decision. Delete it and you lose the only evidence that the question was ever settled, which guarantees somebody reopens it.

That is why a decision log is not a document you maintain. A maintained document tells you the current state, which your codebase or your plan already tells you. A log tells you the sequence, and the sequence is the part that answers questions.

Almost every failed decision log failed because it was doing another artefact's job. The distinctions are sharper than they look.

The confusion that kills logs is the first two. A decision log used as an issue log fills with entries people expect to close, stops being append-only within a month, and then goes stale, because a record that is half to-do list is neither. If an entry has an owner and a due date, it is an action item and it belongs somewhere else.

The minutes boundary is the other one worth holding. Minutes record everything, which is why nobody reads them at the moment they need one fact. A decision log is a deliberate extraction: one entry per decision, findable in a search, without the surrounding discussion. That is the same atomicity argument made about notes in Zettelkasten and evergreen notes, and it works for the same reason.

A minimum viable entry. Ten fields, of which most teams keep six and regret it.

• Id. Sequential, so entries can reference each other.
• Date. When it was decided, not when it was written up.
• The decision, in one sentence. If it takes three, it is probably two decisions.
• Decider. One name.
• Participants. Who was in the conversation.
• Status. Proposed, accepted, or superseded by a given id.
• Context. What was true at the time that made this the question.
• Options rejected, and why. Treated below.
• Consequences. What this commits you to, including the bad parts.
• Link to the source. The meeting, the thread, the document.

The field everyone omits is options rejected, and it is the only one with real value in two years. The recurring question is almost never "what did we decide", because the current state answers that. It is "did we already consider this", asked by somebody new who has just had a good idea that the team had eighteen months ago and discarded for a reason nobody can now recall. Without that field, the honest answer is "probably, but I cannot tell you why not", and the discussion happens again from the beginning.

Context is the second most valuable and the most frequently written badly. It should record what was true then, not what is true now: the constraint, the deadline, the number of customers, the thing you did not yet know. A decision that looks foolish in hindsight is usually a decision whose context was not written down.

The software world arrived at this independently and produced the cleanest version of it. Nygard's architecture decision record has five sections: title, context, decision, status and consequences. It fits on one screen, it lives in the repository beside the code it describes, and a collection of them is an architecture decision log.

Three of its design choices are worth stealing whatever kind of work you do.

One decision per file. Not a page that accumulates. This is what makes them searchable and what makes superseding possible without editing.

Superseding rather than deleting. A new record that says it supersedes number 14, and number 14 stays, marked. The pair of records is more informative than either alone, because it shows the change of mind and the reason for it.

Plain text in version control. The record lives where the work lives and inherits its history, its review process and its durability. ThoughtWorks put lightweight architecture decision records in the Adopt ring of its Technology Radar in 2018, which is about as strong an adoption signal as this kind of practice gets.

The template collection at adr.github.io and Joel Parker Henderson's repository are the practical starting points, and both are more useful than writing your own format.

Outside software the picture is less tidy, and the gap is worth knowing about.

PRINCE2 has always kept a decision trail across registers and logs, and its 7th edition consolidated the daily log, lessons log, issue register, quality register and risk register into a single project log, one of three categories of management product alongside baselines and reports. That is a decision trail by another name and it is prescribed.

PMBOK is the weaker source here, and the weakness is instructive. It has an assumption log, an issue log and a change log, but no decision log as a named artefact and no prescribed mechanism for driving an issue through to a recorded decision. That absence is why this term is owned by practitioner writing rather than by standards, and why the formats in circulation vary so much.

If you are attaching one to a project, the moment to do it is the kickoff. The decisions that get relitigated hardest are the early ones, made before anyone felt the project was real enough to warrant a log.

Three options, and the choice matters less than picking one and putting the link where people already look.

A folder of Markdown files in the repository. Best for engineering decisions. It inherits review, history and search, and it is the only option that is still readable when the tool you chose is gone. The tools that make this pleasant are covered in PKM for developers and Obsidian, Logseq and SiYuan.

A wiki page per decision. Best when the audience is wider than the engineering team. Weakest on durability, because wikis get migrated and entries get flattened.

A table in the tracker. Best for discoverability by people already in the tracker every day. Worst for the append-only rule, because everything in a tracker has a status that people want to close.

Whichever you pick, one rule holds: put the log where the decision will be questioned, not where it is convenient to write.

The second failure is the one everything else depends on, and it is worth being precise about why it happens. A decision is reached in the last ten minutes of a meeting. The person best placed to record it is the person who ran the meeting, who is at that moment the person with the least available attention in the building. Ten minutes later they are somewhere else. That evening, they can recall the conclusion and not the alternatives, which means the field with all the value is the field that is gone first.

Nothing about that is fixed by a better template.

This is where Earkeep fits. It records your day continuously on your own device, transcribes it there, and writes plain files you own, so writing the entry starts from a transcript rather than from memory. You mark the stretch of the day that was the meeting, and an agent running in the panel against it drafts the entry, options rejected included, as a Markdown file in a directory you chose. You correct it, which takes a minute, and that minute is the whole cost.

The durability argument is the same one architecture decision records make. The transcript underneath stays as plain JSONL, one file per day, in a folder you picked, so grep still reads it in ten years whether or not the app is still around. That is the same reason ADRs live in the repository rather than in a tool.

The limits, stated plainly. Earkeep does not detect decisions and does not maintain the log; the reading is done by an agent running on your machine as your own command-line tool, when you ask it to. Nothing runs on a schedule inside the app. The MCP server it exposes is read-only with two tools, so nothing can write back into it. And the record does not identify speakers, so the decider field is yours to fill in. If you want the log cross-linked into a wiki on a schedule, that is your own cron or launchd job running over the files, and the shape of that arrangement is described in the LLM wiki. Telling the room you are recording is yours to do, and there is a page on how to say it.

An entry that took four minutes to write, in the format above. The parts that carry the weight are the last three.

• 0031. 14 May 2026.
• Decision. Customer exports will be generated nightly rather than on demand.
• Decider. The platform lead. In the room: two engineers, the product manager, one person from support.
• Status. Accepted.
• Context. Three customers had asked for exports. The largest had 40 million rows, and an on-demand export of that size took eleven minutes and held a database connection open for all of it. We had one week before the renewal conversation with that customer.
• Options rejected. On-demand with a queue, rejected because it needed a worker tier we did not have and the deadline was a week away. Streaming exports, rejected because the client library the largest customer uses cannot consume a stream. Capping the export at one million rows, rejected because support said the whole point was the annual reconciliation.
• Consequences. Customers cannot get a fresh export mid-day, and support will field that complaint. We now own a nightly job and its failure mode. Revisit if the worker tier arrives.
• Source. Platform sync, 14 May.

Read the rejected options again. In eighteen months somebody will suggest streaming exports, and this entry answers them in one line instead of a meeting. That is the return on the field, and it is why an entry without it is barely worth writing.

How a group reaches a decision in the first place, and which model it is actually running, is collaborative decision making. What the log is not, and the artefact it is most often confused with, is action items. And the wider question of what happens when a year of these records accumulates into something you can query is from what was said to what you know.