Give every shared value exactly one writer
A shop I look after syncs its catalogue to an advertising platform. The sync grew into forty six numbered scripts, seventeen of which arrived on a single day.
Forty five of them read the stock level. One of them wrote it.
It should not have. Stock has exactly one authority, the shop's own inventory, and everything downstream reads and never writes. But that script's job involved stock, it had the record open, and writing the field was one line away.
Nothing errored. Both systems did what their code said. Two writers with different ideas about what a number means is not a failure any single component can detect, which is why it ran for months.
The audit that finds this in an afternoon
This is the useful part. For any system with more than a couple of moving pieces:
- List the values that matter. Stock, price, status, balance, anything a human would notice being wrong. Usually fewer than fifteen.
- For each one, grep for every write. Not reads. Writes. The field name, the setter, the column, the update. Be exhaustive and boring about it.
- Count the writers. One is correct. Two is a bug you have not noticed yet. Three or more means nobody owns it and the value is whatever ran last.
- Write the owner down next to the field, in the code, where the next person will be standing.
I have run this on four systems now. It has found something every single time, and it has never taken more than an afternoon.
Why the comment is not the fix
My first repair was to remove the write and put a loud warning in the file, plus a section in the project rules saying this rule exists because it caused a problem.
That works on whoever reads the file. It does nothing about the forty seventh script, written in a hurry, by anyone, which has the record open and needs one line.
The real fix is structural: the field is not writable through the path those scripts use. Make the wrong thing impossible rather than forbidden and you stop needing people to have read your capitals.
Why this is more urgent now
An agent reads your rules at the start of a session and then spends an hour reasoning toward a solution that happens to need one small write.
It will not be reckless about it. It will be helpful about it, which is worse, because helpful code looks like it belongs. The reviewer sees a sensible change that does a sensible thing, and the fact that it is the second writer of a value is invisible unless you already know the field has an owner.
Which is the argument for doing the audit and writing the owners down. It is not documentation. It is the thing that makes the next review possible.
The one line version
Every shared mutable value needs a named owner, enforced somewhere that is not a comment. Count your writers. The answer should be one.