Why I Keep a Written Record of Every Project Decision

Why do I write down every decision on a project?

Because six months later nobody remembers why, and the absence of a reason is treated as the absence of a decision. Somebody undoes it, or asks me to justify it from memory, and I am arguing from feeling against a person holding an invoice. A written record ends that conversation before it starts.

I work on fixed fees, most projects between one and ten thousand dollars, which means every ambiguity is mine to absorb. That pricing model is the reason this habit exists. When the budget cannot stretch, the only protection is a shared, written understanding of what was agreed and why.

It is not a document anybody asked me for. I started keeping it for myself and gradually noticed it was doing more work for the client than it was for me.

What does a decision record actually look like?

Four lines. The date, the decision in one sentence, the reason in one sentence, and what we chose not to do. That last line is the one that matters and the one everybody leaves out, because the rejected option is what people come back to later without knowing it was already considered.

No formatting, no template, no tool worth arguing about. A plain document that both sides can read. I have used Notion, Google Docs and a text file, and the tool has never once been the reason it worked or did not.

Length is the discipline. If it takes more than a couple of minutes to write, I will stop doing it inside a fortnight, and a habit I abandon is worse than one I never started because now there is a partial record that looks complete.

Which decisions are worth recording?

Anything where a reasonable person could have chosen differently. If there was only one sensible option it is not a decision, it is a fact, and facts do not get relitigated. The moment I can imagine somebody asking why did you do it that way, it goes in.

In practice that is structural choices, naming, anything deferred to a later phase, and anything the client asked for against my recommendation. That last category is the most important and the most uncomfortable to write, which is exactly why it has to be written at the time rather than remembered afterwards.

I write those neutrally. Client prefers to keep the existing structure, I recommended consolidating, we are proceeding with the existing structure. No editorialising. When it comes up again, and it does, the record is a reference rather than an accusation.

It also means I am not the only place the project's reasoning lives, which is a failure mode I have written about separately in being the only person who knows how it works.

Who is it really for?

The person who inherits the site. Not the client I am talking to now, but whoever replaces them, or the developer who picks it up in two years, or me after eleven other projects have pushed the details out of my head.

Handover documentation describes how things work. A decision record describes why they are that way, and those are completely different questions. The first stops somebody breaking the site. The second stops them rebuilding something that was deliberately not built.

The clearest signal it is working is when a client quotes it back to me. That means the reasoning transferred, which is the actual deliverable. The site is just where the reasoning ended up.

How has it changed the scope conversation?

It made it shorter and much less personal. When a request arrives that contradicts something agreed earlier, I am not saying I think we discussed this. I am pointing at a dated line and asking whether the reason still holds. Often it does not, and then the change is legitimate and we price it.

That reframing matters more than the document. Scope disagreements get bad when they become a contest of memories, because one side is a paying customer and the other is a supplier, and that asymmetry decides most contests of memory. A written record removes the asymmetry entirely.

It has also made me more willing to say yes to changes, which surprised me. When the boundary is documented, moving it is a deliberate, priceable act rather than a slow leak, and I went into what that looks like in when a fixed fee project goes over scope.

What did it cost me to learn this?

Time I could not bill and goodwill I could not get back. In my first years I relied on memory and email threads, and email threads are a terrible record because they contain the discussion rather than the conclusion. Finding the moment something was agreed inside a forty message chain is worse than having no record at all.

The specific pattern that taught me was always the same shape. A decision made verbally on a call, implemented, and questioned months later by somebody who had not been on the call. I could explain the reasoning perfectly well. What I could not do was prove the reasoning had existed at the time, and to a new stakeholder those are indistinguishable.

I will not pretend I know what that cost in hours, because I never measured it and I am not going to invent a number. What I can say is that the habit is free and the alternative was not, and it took me longer than it should have to change.

Where does this fail?

When it becomes a compliance exercise. The moment a decision record has a required format with fields nobody reads, it stops being a thinking tool and becomes overhead, and overhead gets skipped under pressure. Which is precisely when you need it.

It also fails when it is kept somewhere the client cannot see. A private log is a defensive document, and a defensive document produces a defensive relationship. It has to be shared from day one, or it will read like evidence you were assembling rather than a record you were keeping.

And it does not help with things nobody thought to decide. The worst problems on a project are usually not wrong decisions, they are questions nobody asked. A record of decisions says nothing about those, which is why good discovery still matters and why I care what a client asks me at the start, something I set out in what a client should ask me before hiring me.

Does working with AI tools change any of this?

It makes it more valuable, not less. When an assistant can regenerate a page in minutes, the scarce thing is no longer the work. It is knowing which constraints the work has to respect, and that knowledge lives in the decisions rather than in the files.

I feed these records in as context now, and the quality of what comes back is noticeably better when the reasoning is available than when only the current state is. A model reading a site can tell you what is there. It cannot tell you what was deliberately left out, unless somebody wrote it down.

That has made me stricter about the rejected option line, not looser. It is the only part of the record that captures a path not taken, and paths not taken are exactly what an eager assistant will happily rebuild for you.

What should you do next?

Open a document on your current project and write the last three decisions you remember making, with the date, the reason, and what you chose not to do. It will take ten minutes and you will immediately notice how much of the reasoning has already gone fuzzy.

Then share it with whoever you are working with and add to it as you go. Do not build a template, do not pick a tool, do not announce a process. Just keep the four lines and let it prove itself over a few months.

If you are running projects where the same arguments keep coming back and nobody can remember what was agreed, this is usually the missing piece. Reach out if you want to talk through how you are working. Let's chat.