A decision log, and why the reasons in it matter more than the decisions

A decision log is the running record of what was decided, by whom, and on what basis, kept as things happen rather than reconstructed afterwards. DECISION keeps one in the tab: numbered entries with the reasoning, the rejected options and what the decision rested on, each sealed with a SHA-256 taken over the entry before it, so that altering any entry changes the seal at the head of the log. Nothing is uploaded.

What a log is actually examined for

The common misunderstanding is that a decision log exists to show that the decisions were good ones. It does not, and it cannot: whether a decision was right is judged against what happened next, and the log is written before that is known.

What it is examined for is narrower and much harder to fake after the fact:

• What was known at the time. Not what turned out to be true. A decision made on three pieces of information is judged on those three, and a log that does not name them leaves the reader free to assume you knew the fourth.
• What else was considered. An entry recording only the chosen option reads as though nothing else occurred to anybody. An entry that names two rejected options and why they were rejected reads as a decision. This is the single most common omission, and the one that does the most damage in a review.
• When it was written down. A log written up at the end of the week is a different document from one written as things happened, and everybody reading it knows the difference. Recording both times is more credible than recording one, because a gap that is stated is a gap that was not hidden.

A log built around those three questions survives being read by somebody looking for a problem. A log that records outcomes and dates does not.

Where this shape comes from, and where else it fits

The form is familiar from policing and emergency management — a senior investigating officer's policy file, a firearms authorising officer's log, a Gold or incident commander's log — where the practice of writing the reasons down as you go is long established, because the alternative has been tested in court repeatedly and does not hold up.

The same shape fits anywhere decisions are examined afterwards by somebody who was not there: safeguarding, clinical governance, procurement, redundancy and disciplinary processes, incident response, a board or a set of trustees. In ordinary commercial life it is the file that gets disclosed when somebody sues. The field names in the tool are deliberately plain rather than borrowed from any one profession's vocabulary, for that reason.

What a hash chain does, and what it does not

Each entry is turned into a canonical text — every field in a fixed order, each length-prefixed, so that moving a line break from the end of one field to the start of the next cannot leave the text unchanged — and a SHA-256 is taken over the previous entry's seal followed by that text. Because each seal depends on the one before it, the entries form a chain. Change entry three and entry three stops verifying, and so does four, and five, and every entry after it.

Here is the part that is usually oversold, so it is worth being blunt about: this does not prove you did not go back and change something. Anybody who can edit the browser's storage can recompute every seal in the log and produce a chain that verifies perfectly. A chain kept entirely under your own control proves nothing to somebody who does not trust you.

What it gives you is that an alteration cannot be made quietly. The seal at the head of the log is recomputed by walking the chain from the first entry forward, not by trusting the seals already stored, so changing anything anywhere changes the head seal. Write that seal down somewhere outside the log — in an email you send yourself, in a case management system, in a notebook, read out in a meeting — and you have created a moment that anchors the whole log to a point in time. An alteration afterwards is then visible to anybody who compares the two.

That is a modest claim, and it is the true one. The value is in the anchor you make outside the log, not in the arithmetic inside it.

Correcting something

Two different things get called corrections and they need opposite treatment.

A typo. Fix it. The entry is re-sealed, every entry after it is re-sealed, and the head seal changes. That is not a flaw; it is the mechanism working. But it means any head seal you had written down no longer matches, so write the new one down and note why it changed.

A decision that has moved on. Do not edit the entry. Write a new one that supersedes it. Both stay in the log, each marked with the other, and the printed log shows the change of mind with both sets of reasons intact. A log in which nobody ever changed their mind is not a more impressive document than one in which somebody did and said so — it is a less believable one.

Why this belongs on your own machine

A decision log names people, sometimes before anything has been established about them, and it records reasoning that is candid because nobody expected it to be read by a stranger. That is exactly the material that should not be sitting in somebody else's database waiting for a breach, a subpoena or a change of terms.

Hashing and text are arithmetic a browser does in microseconds. There is no technical reason a decision log needs a server, and several good reasons it should not have one.

The short version