Written context prevents misinterpretation

The idea

Recording the context of a decision prevents future confusion about why you made it. Without a written record of the forces, constraints, and reasoning at the moment of choice, your future self — and everyone else — will reconstruct a fiction and call it memory.

In 2011, software architect Michael Nygard published a short essay titled "Documenting Architecture Decisions" that diagnosed a problem plaguing every software team he had ever worked with. Teams would inherit codebases full of decisions they did not understand. Why was the system built this way? Why was this technology chosen over that one? Why does this constraint exist? The answers were gone — dissolved into the memories of people who had left the company, buried in Slack channels nobody would ever scroll back to, or simply never written down at all (Nygard, 2011).

An example

A software team inherits a codebase that routes all database queries through a single connection pool limited to five connections. The new developers find this baffling — the database can handle hundreds of concurrent connections. They spend two weeks refactoring the pooling layer to remove the "bottleneck." The system immediately crashes under load. Three escalation calls later, a former team member explains: the original database server had a licensing restriction that capped concurrent connections at five. The pool limit was not a mistake. It was a deliberate architectural decision made to prevent license violations that would have shut down the entire production system. The constraint had been removed when the company migrated to a new license two years ago, but nobody recorded why the pool limit existed in the first place. Two weeks of engineering time, a production outage, and a licensing near-miss — all because the context of the original decision was never written down. Had the team maintained an Architecture Decision Record stating "We limit the pool to five connections because our database license caps concurrent connections at five; revisit when the license changes," the refactoring would have taken thirty minutes of verification instead of two weeks of archaeology.

Where it goes wrong

The most common failure is not refusing to document decisions — it is documenting the decision without documenting the context. People write "We chose React" without writing "because our team had three React developers and zero Angular developers, we had a six-week deadline, and the client required server-side rendering which React supported through Next.js." The decision without the context is a fact without meaning. Six months later, when the team has changed and the deadline is forgotten, "We chose React" provides zero information about whether the decision still makes sense. A second failure mode is documenting context in ephemeral channels — Slack messages, meeting conversations, verbal explanations. This context exists for hours or days before it is buried under new messages or forgotten entirely. If the context is not written in a place that persists alongside the decision, it might as well not exist.

Make it stick

Create a Decision Context Log — a single document, note, or folder where you record the context of every significant decision you make this week. Use the format from the exercise: decision statement, context, expected consequences, confidence level. The threshold for "significant" is any decision where you consider more than one option for more than sixty seconds. At the end of the week, review the log. Count how many decisions you made that you would have already forgotten the reasoning behind. This count is your context loss rate — the percentage of your own thinking that evaporates without written records.