Logged
A principle you have to remember is not a principle. It is a hope with good posture.
Here is how we found that out.
The discovery
We keep a set of commitments we do not negotiate. They are written down, they predate any pressure to break them, and they are supposed to be the last thing that moves.
In August we went looking for one of them and found it in nine different places in our own documents. Three of those were the list itself. The other six were restatements, written at different times, by people making an honest local edit.
Someone had already noticed and shipped a fix. The fix updated two of the nine.
The patch that predicted its own failure
The part worth writing about is not the mistake. It is what the person who wrote the fix put at the bottom of it, before anyone had complained:
This patch is a symptom-level fix. This commitment exists in seven places and the patch has annotated two of them. It will break the next time someone edits only one of them.
They knew. They wrote it down. And it was still going to break, because knowing is not a mechanism.
That is the part to take seriously. It was not carelessness. It was a correct diagnosis, filed, and then left to depend on somebody remembering it at the exact moment they were busy.
Why we could not just fix it properly
The obvious repair is to have the commitment exist in one place and be referenced everywhere else. One source, no drift.
We could not do that. Those documents can only be changed by one person, deliberately, and this workspace is explicitly not permitted to edit that repository. The correct fix was out of reach for reasons that were themselves principled.
So the choice was: leave a known future failure in place, or build something that catches it.
The gate
We wrote a check that runs on every commit and asserts that all nine commitments still say the same thing in every place they appear.
The interesting part is what the check deliberately does not do.
It does not require the wordings to be byte-identical. They are not identical today, and that is legitimate — one place says "we don't charge in place of" and another says "we don't charge for"; one uses curly quotation marks where three use straight ones. Those differences are how the documents were actually written. They are not drift.
Had we required exact equality, the check would have failed on the day we wrote it, and failed for reasons carrying no information. And there is exactly one thing a permanently red check ever teaches a team:
A gate that is always red trains people to loosen the criterion.
So it has two layers instead. First, it pins the exact wording of every location as of today; if any single one changes, it reports which one drifted, what it drifted into, and what all the others currently say. Second, wherever the wordings are already equal it asserts they stay equal — and wherever they already differ, it records that specific difference and asserts the difference is still exactly the one on record.
The result is a check that goes red only when something real has moved, and that tells you what moved rather than merely that something did.
What we actually changed our mind about
We used to treat "write it down" as the fix. It is not. It is the receipt.
The ordering we work from now:
- Mechanical — a type, a constraint, a check that fails the build. It stops the mistake at the moment it is made, and needs nobody to remember anything.
- Documented — works only when somebody opens the file.
- Remembered — works only when somebody happens to think of it.
Anything surviving purely on the third is not yet fixed, and we have agreed to say so out loud rather than mark it done.
This particular gate is 611 lines protecting nine sentences. Written down, that ratio looks absurd. It looked absurd to us too — until we counted how many places one of those sentences had quietly gone to live.
This is a build log. It describes work already done, not a plan.