By ·

The Decision Journal: Why We Log What Changed Instead of Rewriting What Was

Technical specifications change. That is not a problem. The problem is how most teams handle it.

Someone opens the document, rewrites the paragraph, and saves the file. The old requirement disappears. A month later, a developer asks why a particular architectural choice was made, and nobody can answer. The reasoning walked out the door with the deleted text. The team is left building on a foundation they cannot explain.

We ran into this early enough in our work to treat it as a structural problem rather than a communication one. The solution we landed on is not complicated, but it requires discipline: keep a decision journal alongside the technical specification, and never let the two jobs overlap.

Two Documents, Two Jobs

The technical specification describes how things should be right now. Present tense. Current state. A developer or an AI agent reading it should encounter clean, unambiguous requirements with no historical commentary, no "as discussed," no "per the client's earlier request." If you can remove every mention of parties and dates from a paragraph and the requirement still stands on its own, the paragraph belongs in the spec.

Two documents, two job opportunities.

One exception: reasoning stays in the spec when the developer needs it to get the requirement right, such as a physical or legal limit, a constraint from a standard, or a measured value. Everything else about how a requirement came to be belongs in the decision journal.

The journal holds everything the spec deliberately excludes: what was decided, when, on what basis, and what it replaced. Every entry carries a number, the decision itself, a status, and a source: a dated client reply, the development owner’s approval, or a technical decision. When a decision changes, the old entry does not get deleted. It gets marked "Replaced" with a reference to the new entry. If the new decision refines rather than overturns the old one, the status reads "Clarified" instead.

This distinction matters more than it sounds. A team that only sees the current state of a document cannot reconstruct the reasoning that produced it. A team that can trace every change, back through every revision, can answer the question "why did we build it this way?" with a date and a source, not with a guess.

The practice is not invented from scratch. Michael Nygard's 2011 notes on architecture decision records proposed the same principle: do not delete a superseded decision; mark it as replaced so that new people on the project neither blindly accept past decisions nor blindly reverse them. We applied that principle to the full client-facing specification process, not just to the internal engineering layer. The underlying logic holds in both contexts.

What the Journal Looks Like in Practice

On a recent e-commerce build, the product decision journal accumulated more than 200 entries over the course of the project. A separate journal tracked design session decisions, with roughly 300 entries of its own. That is not bureaucracy. It is the only reliable way to answer, three months into a project, why a particular feature works the way it does.

Journal entries show decisions, path, and version history.

A concrete example: at the start of that project, we decided to keep the backend in a separate repository. Later, it became clear that a shared repository with an independent build configuration was more practical. Both decisions are in the journal. The first entry carries the status "Replaced" with a link to the second. Anyone who opens the journal sees not just the outcome but the path that led to it. That traceability is worth something, especially when a new team member joins midway through or when the project is handed off.

The version table in the spec itself follows the same logic. Over three months, the document passed through more than 20 versions, now closer to 30. Each row in the version table records what changed in substance: a section added, an estimate revised, a catalog scope adjusted. A version number only increments when a decision has changed the scope of work or the estimate. Rewording a sentence does not move the version. That means when a client sees that the version number has gone up, they know something material changed and it is worth their attention.

We also ran into a specific failure that made the single-source-of-truth rule permanent for us. At one point, a time estimate appeared in both the technical specification and the estimation document, stated as independent values. Predictably, they drifted. By the time the discrepancy surfaced, tracing the correct number required going back through both documents and comparing dates. The fix was simple: the second document references the first rather than repeating the value. Every number now carries a note on its basis: measured, derived from other figures, or treated as an assumption. When a figure is an assumption, that is stated explicitly, alongside a range if the estimate was still open at the time.

Priority Order and the Risk Register

In a project with multiple documents, contradictions are not a failure of process. They are an inevitability. The question is how to resolve them without a dispute.

Prioritize documents and risks; resolve contradictions decisively.

We document the priority order at the start: the decision journal takes precedence over the technical specification, which takes precedence over the product contract. When two documents say different things, there is no argument about which is right. The order is already written down, and the mismatch gets fixed.

The same non-deletion principle applies to risks. The risk register tracks only items that could affect the scope of work, the architecture, the sequencing, the estimate, or the launch. Minor unknowns stay inside the relevant sections of the spec and do not inflate the risk list. When a risk is resolved, it is not removed. It receives a "Closed" status with a date, and the outcome is carried into the spec or the decision journal as appropriate. If a risk is still open at the time of estimation, the entry records the assumption made and the range built around it.

Where AI Fits In

The decision journal is one of the most useful documents we can give an AI agent. Before an agent interprets an ambiguous requirement or proposes a change to the scope, it reads the journal. It will not propose something that was already rejected. It will not rely on a decision that has since been replaced.

**HUMAN DECIDES** → **DECISION JOURNAL** → **AI UPDATES SPEC**

AI also helps maintain the journal itself. After a client responds to an open question, the AI logs the new entry, sets the appropriate status on the prior entry, identifies which sections of the spec the new decision touches, and rewrites those sections to reflect the current state. It then checks the full document set for inconsistencies between what was just decided and what other documents still say.

This is the same pattern we described when writing about the spec before the spec: humans define the structure and approve every decision; AI keeps the structure populated and consistent. The model reasons, flags, and drafts. The person signs off.

It connects directly to something we covered earlier about how conversations become structured records: once every exchange is captured as a file, the decision journal becomes the layer that makes those files navigable and easy to trace. Files without a priority order and a status system are just an archive. With them, they become a source of truth.

Why This Matters Beyond the Project

The practical gain is straightforward: you can change decisions without creating chaos. The current state of requirements is always visible and always clean. The reasoning behind that state is always traceable and always dated.

Traceable decisions, clear history, adaptable projects.

Developers build from the active version, not from a requirement that was quietly superseded four weeks ago. AI agents do the same. When a client asks, six months after launch, why the catalog is structured a certain way, the answer is a journal entry with a date and a source, not a conversation someone half-remembers.

The technical specification stays short because it carries no history. The history lives in the journal, which is exactly where it belongs.

Decisions change. The only real question is whether you can explain why, and when, and what replaced what. The journal makes that possible without requiring anyone to remember.