Architecture Decision Record vs Decision Log, and Why Both

2026-09-06 · Yesterself

The two records get confused because they sound like the same object. An architecture decision record is a short document you commit next to the code so that a future maintainer, possibly someone who has never met you, can understand why the system is shaped this way. A decision log, the private kind, is a page nobody else reads, where you write what you predicted, what you were afraid of, and how sure you actually were.

They share one line. They diverge in everything after it. Keeping them separate is what makes both of them honest.

What the ADR is for

Michael Nygard described the format in a 2011 post on documenting architecture decisions, and the shape has barely moved since: a numbered file per decision, with Title, Status, Context, Decision, and Consequences. The status moves from proposed to accepted to superseded. You do not edit an old record when you change your mind. You write a new one that supersedes it, so the trail stays readable.

The important property is not the template. It is the audience. An ADR is written for a reader who arrives late, has no memory of the argument, and needs two things: why is it like this, and what was already considered so I do not re-litigate it on Tuesday.

That audience shapes the prose whether you intend it or not. You write the defensible version. You give the reasons that survive being read aloud in a room. This is not dishonesty. It is register. A record meant for strangers should be written in the language strangers can check.

What an ADR structurally cannot hold

Because of who reads it, a good ADR leaves out most of what actually moved the decision:

• Your confidence. "We chose Postgres" hides "I was about sixty percent on this and forty on the other one."
• The real tiebreaker. Often it was that one person already knew the technology, or that the deadline was in March, or that you were tired of the argument.
• The prediction. An ADR says what you decided. It rarely says what you expect to happen by when, in a form that can later be wrong.
• The fear. The specific failure you pictured at 2 a.m. and did not put in Consequences because it sounded alarmist.
• The people. Who pushed, who went quiet, whose objection you overruled and whether you were right to.

None of that belongs in version control, and the reasons are practical rather than squeamish. A repository outlives your employment. It gets forked, mirrored, and backed up, and once a commit has been pushed, a sentence you regret is not reliably deletable. It is searchable by everyone with read access, including the colleague you named. Write the register the medium can carry, and keep the rest somewhere it can be plain.

The four lines of a private decision log

A useful private entry is short. Four lines, written the same day, before the reasoning fades into a story:

1. The decision and the date. One sentence, in the same words as the ADR title. This is the join key between the two records.
2. The alternative you nearly took, and the actual tiebreaker. Not the presentable reason. The one that decided it.
3. A prediction with a date and a number. "By March, query latency is under 200ms and we have not needed a cache. 65 percent." Philip Tetlock's forecasting research, which scored thousands of dated predictions against what actually happened, found that forecasters got better when they attached a number and then checked it, rather than relying on memory.
4. What you are afraid of. One line. The version you would not say in standup.

An optional fifth line is the most valuable of all once you have a few months of these: what would have to be true for me to reverse this? Naming the tripwire in advance is close to the old Stoic exercise of rehearsing what could go wrong, which is worth doing deliberately rather than at 2 a.m. — more on that in premeditatio malorum as a writing practice.

What to duplicate and what to keep out

Duplicate exactly one thing: the sentence naming the decision, and the date. That is enough to find the ADR from the log and the log from the ADR.

Keep out of the private log anything that is confidential in substance rather than in tone. Your log is a record of your reasoning, not a copy of your employer's material. "The vendor's uptime numbers did not hold up" carries the reasoning without carrying the contract.

One plain caveat, because this is about records and employers. None of it is legal advice. Calling a log private is a description of who you show it to, not a legal status: what counts as confidential material is set by your contract and by where you work, and a record about work can still be reached by an employer or by a legal process. If the decision touches a contract, an incident, money, or another person's conduct, ask a lawyer where you work before you decide where the record lives.

And set a review date at the moment you write, not later. This is the part everyone skips. A decision reviewed when you happen to remember it is a decision reviewed only when it blew up. Whatever holds your log needs to be able to hand the entry back to you on a chosen day. In Yesterself, a sentence can be postmarked to a future date and arrives that morning as mail. The tool matters less than the principle: the review has to be scheduled by the version of you who made the decision, because the version three months out is busy and has already decided it was obvious.

Grading yourself once the ADR is forgotten

When the entry comes back, do it in this order, and the order is the whole trick.

Read your prediction first. Do not look at the outcome yet. Notice what you feel about the prediction before you know whether it landed. Then write what actually happened, in two sentences. Then grade.

The order matters because of a well-documented effect. In the 1970s Baruch Fischhoff ran experiments showing that once people learn an outcome, they overestimate how likely they would have said it was beforehand — hindsight quietly rewrites the memory of your own uncertainty. Reading the outcome first means you will grade a prediction you no longer have. Reading the prediction first preserves it.

Then grade two separate things:

• Calibration, not correctness. Take every entry where you wrote 70 percent. Roughly seven in ten should have happened. If ten out of ten did, you are underconfident and slow to commit. If four did, you are talking yourself into things.
• Decision quality versus outcome quality. A good call can go badly. Ask whether you would make the same decision with the information you had on the day. If yes, the outcome was luck, and the entry is still a win.

Across a year of entries, the patterns are more useful than any single grade. The fear that shows up in every entry and has never once materialized. The tiebreaker that is always "whoever argued longest." The predictions that are always right at three months and always wrong at twelve, which tells you something exact about your planning horizon.

The ADR will be superseded, and nobody will hold a retrospective on it. Your log is the only place that review happens, and it only happens if the entry comes back to find you. Write the record your team needs. Then write the one that is only for you.

Common questions

Should my private decision log live in the repository?

No. A repository is shared, searchable, effectively permanent, and outlives your job there, so it is the wrong home for confidence levels, fears, and judgments about colleagues. Keep the log wherever your private writing already lives, and duplicate only the decision sentence and the date.

Isn't this duplicate work for the same decision?

Only the first line is duplicated. The ADR answers why the system is like this for a future maintainer, and the private log answers what you predicted and how sure you were, which is content the ADR never contained in the first place. The private entry takes about two minutes.

What if I don't want to write probabilities?

Use three buckets instead: fairly sure, leaning, or a coin flip. The value comes from committing to a level before the outcome is known, not from the precision of the number.

Do I still need ADRs if I work alone?

A lightweight one is usually still worth it, because the future maintainer of a solo project is you in two years with no memory of the constraint you were working around. The private log is separate and answers a different question about your own judgment.

How long should I wait before reviewing an entry?

Set the date when you write it, tied to the prediction rather than to a fixed interval. Ninety days is a reasonable default for most technical calls; anything involving hiring, architecture rewrites, or team structure usually needs a year.