The Shape of a Decision

In 2005, Petter Johansson ran an experiment where participants chose which of two photographed faces they found more attractive. The researcher then slid the chosen photo away and handed them the one they hadn't picked, then asked them to explain their choice. Most people didn't notice the swap. They proceeded to explain, with complete conviction, why they had chosen the face they had, in fact, rejected.

Johansson called this "choice blindness." The part I keep returning to isn't the substitution. It's what happened when the manipulation was revealed. Most participants simply updated their reasoning to fit the new fact. They weren't lying. They believed the story they were telling. The decision, as they experienced it, was the explanation they'd already constructed.

Decisions aren't well stored in memory. We retain the outcome and reconstruct the reasoning on demand. This sounds like a psychological curiosity. It has serious implications for anyone who tries to use past decisions to inform current ones.

What a decision note actually records

I kept a running document of decisions while building Harbor: architecture calls, product choices, things I decided not to build yet. For a while, those were prose notes. "Decided to use SQLite per workspace. Simpler to self-host." "Chose not to add real-time collaboration in v1." Useful at time of writing, when the context was still obvious. Not useful six months later, when the note read like someone else's certainty.

What wasn't in those notes: the alternatives I'd considered. The constraint that made one option impractical. The condition under which I'd revisit. Without that, the note records that a decision existed, not what the decision actually was.

Michael Nygard noticed this problem in software teams and wrote about it in November 2011, in a short post on Cognitect's site called "Documenting Architecture Decisions." The problem was specific: teams kept relitigating choices. A new engineer joins, sees a system built a certain way, doesn't understand why, considers changing it, and either wastes time researching a decision already made, or undoes it without realizing the original constraint still applies.

His solution was the Architecture Decision Record: a short, structured document with a fixed shape. Title. Status. Context. Decision. Consequences. Not a free-text note about what was decided. A record of why — the forces in play, the alternatives that were ruled out, what you expected to happen as a result.

The insight that made ADRs useful wasn't the format. It was the recognition that a decision has structure, and that structure exists at the moment you're making it, not when you're trying to reconstruct it later.

Why timing matters

Most notes fail as decision records because they're written after the decision is already made. The alternatives have receded. The constraints feel obvious, not worth mentioning. You write down what you chose and the first-order reason. Johansson's participants were doing the same thing: producing a retrospective narrative that felt true, because by that point it was the truth they had access to.

ADRs force you to write context before you write the decision. Or at least, to capture it while you're committing to a path, when the full picture is still in the room. The Context section isn't background. It's everything that constrained the decision: the timeline, the API you couldn't change, the tradeoff you were explicitly accepting. Consequences include what you're giving up. That last part is the thing almost nobody writes in a normal note.

It's tedious to do this. Which is probably why most people don't.

The retrieval problem

I've been thinking about what this means when AI reads your knowledge base.

When a model queries your notes and finds "Decided on X, might revisit later," it can surface the fact of the decision. It cannot tell you: what were the alternatives? What constraint made X right at the time? Under what conditions should you revisit? Those things either weren't written, or exist only in prose that doesn't survive extraction as discrete, queryable facts.

Typed entities change this. A decision record isn't a note with the word "decided" somewhere in it. It has fields: context, options considered, choice made, reasoning, current status. When an AI reads that structure, it can answer qualitative questions, not just "what did you decide about X" but "is this decision still valid given that the constraint has changed?" That's a different kind of retrieval from keyword search over notes.

What Nygard's post was really about

What strikes me about the original 2011 post is how short it is. Five sections. Fewer than five hundred words. The problem he was solving, teams forgetting why they built things, is unsurprising. What was surprising is how much it helped to simply name the structure a decision already has.

That structure exists in every personal decision you've ever made. The alternatives you weighed. The constraint that ruled most of them out. The thing you'd want to know if you faced this question again next year. None of it shows up in a note that says "decided on X."

Johansson's participants weren't bad decision-makers. They just couldn't tell the difference between the story they'd constructed and the decision they'd actually made. Neither can the rest of us. The gap between "what I chose" and "why I chose it" closes faster than you'd expect, usually within hours. The only thing that helps is writing it down while both things are still in the room.

---

Asgeir Albretsen is the founder of Harbor.