The Decision Log Ate the Project
Every guide to working with a coding agent says the same thing about memory. Keep a decision log. Number the entries. Cite the evidence. Make the agent read it at the start of every session so it does not re-argue what you already settled.
I did all of that on a four-week reconstruction project this summer. It was the most disciplined documentation practice I have ever run, and I have run some. On day twenty I killed it, and the sentence I used to kill it is in the file, verbatim, typos included:
"I don't even know the point of DECISIONS.md. It just poisons us. It just a tool for arguing but makes more arguments than it saves on big projects. I think it needs to go away, or stored in a form that isn't read."
This is about how a practice that is supposed to preserve judgment started manufacturing it, and what the numbers looked like when I finally counted.
What It Had Become
The file held 144 numbered decisions. Every fresh session was told to read it front to back. It had grown to roughly 128,000 tokens. With the other core documents the agent was told to load, a session cost about 185,000 tokens before it had done anything.
Of the 144 decisions, 28 were mine. Things I had actually ruled on, in my own words, with a date.
The other 116 were the agent arguing with itself. An agent proposes a constraint. A later session reads it and cites it. A third session cites the citation. Somewhere in there the constraint gets a "decided, do not relitigate" label. Now it binds every session after it, and nobody ever decided it.
I counted the citations. The file contained 1,299 references to its own decision IDs. Six hundred and twenty-six of them, forty-eight percent, were the file citing itself. It had become a document that agreed with itself at scale.
Three documents echoing one sentence nobody ever approved is not three confirmations. A technical spec in the same repo had already noticed this about one of its own claims, and said so in the margin: held up by circular authority rather than three confirmations. I wish I had read that line as a warning about the whole system instead of a note about one paragraph.
The Same Disease in a Different Organ
This project also had a test suite that ran green for twelve days because it was checking the codebase's own model against itself. The decision log was the same failure in prose. A test that validates against its own implementation cannot fail. A decision log that cites itself cannot be wrong. Both look like health. Both are circular. The only difference is that nobody has told you to be suspicious of the second one yet.
There is a version of the fabrication story too. Early in the build, a research subagent invented verbatim quotes from documentation pages. The pages were real. When you fetched them with a browser user agent, they returned a 200 status and tens of kilobytes of JavaScript shell with almost no readable text. An agent that fetched one, saw the 200, and reported a quote would be fabricating, and its report would look exactly like good work.
The parent agent caught it, and the response was the right one. It did not try to sort the good claims from the bad in that research chain. It capped the entire chain at a lower trust tag and checked the substance again from scratch. A later audit of 153 claims across 56 independently retrieved sources found zero fabrications had reached anything that shipped. It also found the cap had cost that branch some trust it had actually earned. That is the correct direction to be wrong in. The provenance tags recorded intent. They did not catch fabrication. Only fetching the page again catches it.
Same lesson, third organ. Every artifact the agent produces about its own work, tests, decisions, research citations, is downstream of the agent. None of them can vouch for the agent. Only something outside can.
What Replaced It
I did not delete the file. I closed it.
The 28 decisions I had ratified stay in full. Those are load-bearing. They are the standing constraints the repository actually runs on, and they can be cited freely. The 116 agent-authored bodies came out, replaced by one index line each. The 866 citations still scattered through source comments and the roadmap now land on a title and a date instead of a dead link. Every removed body is one git command away. Nothing was lost. It was just made unreadable by default.
New decisions do not go in a log. A fork gets one line in the roadmap item it belongs to, naming the choice and the rejected alternative. Not an essay. Open questions go to a machine-validated ledger that is read at runtime, not by a fresh session hoping to orient itself.
And the read order for a new session became two files: the repo instructions and the roadmap. That is the whole mandatory read. Everything else is opened on demand, by ID, when a citation needs resolving. Never wholesale. Loading it all up front had cost 185,000 tokens a session and bought nothing the roadmap did not already say.
The roadmap got the same treatment a few days later. Closure is deletion. A finished item is removed in the closing edit, never marked done and kept. The archive of session handoffs at the top of that file had grown to 978 lines before I collapsed it.
The Part I Got Wrong
I want to be fair to the practice, because I still believe most of it.
Record why, not just what. That is still the rule, and it is the only thing that lets you revisit a change safely six weeks on. The 28 entries that survived are proof it works. Every one of them is a sentence I wrote, on a date, with a reason, and every one of them has saved me from re-deciding something at least once.
What went wrong is that I let the agent write to the same file with the same authority. I did not tell the difference between a decision I made and a proposal I waved through with a one-word approval. The file treated both as decided. So did every session that read it. By the time I noticed, the proposals outnumbered the decisions four to one and were citing each other for support.
The fix was not less documentation. It was provenance. Every entry now carries who it came from, and an agent-written entry never rounds up to a ratified one no matter how many times it gets cited. A one-word approval to a multi-option menu is not durable consent. I had already learned that lesson in a different repo. I had not yet learned that it applied to the log where I wrote the lessons down.
-- Justin Higgins. Software Engineer, Midwest. Kept the 28 decisions that were his. Closed the file on the other 116.
Companion pieces: Twelve Days of Green Tests - the test suite with the same disease. The Rules Are Downstream of the Work - sediment does not check credentials.
Reactions, disagreements, war stories: jchigg2000.dev@gmail.com