Written, and never wired

A storekeeper types the wrong quantity into a goods receipt. It happens the way every typing mistake happens: at the end of a long afternoon, on a phone, with a lorry waiting.

There was no way to undo it. The number stayed wrong, and the correction happened on paper, in a note, and in the head of the one person who remembered which entry was the bad one.

The strange part is that the code to undo it already existed. It had been written. It had no callers at all. No button, no menu item, no route: a complete, plausible, entirely unreachable function.

This is one of the commonest things we find#

It is not a curiosity. On the same system, two buttons — send this document for signature, and open it in the document editor — had never once appeared for anybody, on any screen, in the whole life of the feature. Both were gated on a flag meaning "this file can be edited as text", which is false for every PDF there has ever been. The feature worked. Nobody could reach it.

Elsewhere, text had been machine-read out of well over a thousand photographs sent from site, and stored, and nothing had ever looked at it. The check that should have used it read only the caption somebody typed, and site photographs usually have no caption, because the delivery slip in the picture already says everything.

Built is not the same as reachable. Reachable is the only one a person experiences.

Wiring it up was not safe#

This was the lesson we did not expect, and it is the more useful one.

Code that has never run has never been wrong out loud. It has been reviewed, probably, and it reads correctly, and it has never once met a real store, a real lorry or a real person in a hurry. Six faults had to be fixed before that undo could be given a button. Some of them, in shape:

• It marked the original entry as cancelled, and one of the readers that counts stock never checked that mark. A cancelled receipt would have gone on counting for ever, and the balance would have been wrong in a new way.
• It never asked whether the stock had since gone out again. Cancelling a receipt after most of it had been issued would have driven the balance below zero, silently, which is not a state a store can be in.
• Its permission check asked only whether you were an administrator, so anybody whose name was on a row could cancel that row.
• It could reach through the store's door and cancel an entry that the gate had written, leaving the gate's own register saying the lorry arrived and the entry impossible to put back.
• The reason for the cancellation never reached the audit trail, because the trail reads the reason from the record's new state and no reason was ever handed to it. Every cancellation would have been recorded as having happened for no stated reason.

None of those is a careless mistake. Each is the kind of thing you discover the first time the code meets the world, and this code never had.

What it does now#

A cancellation writes two halves in one movement: the original marked cancelled, and a reversing correction of the opposite sign which is born already cancelled itself.

That shape is deliberate. A reader that filters out cancelled rows sees neither half. A reader that forgets to filter sees both, and both add to zero. The answer is correct under either reading, which is what you want when you cannot personally audit every piece of code that will ever count your stock. It is also keyed so that a second reversal of the same entry is impossible.

Before it acts it states the effect in numbers: the store reads this much of this material, cancelling this entry leaves that much. And it requires a reason, which now actually arrives in the record.

Why nobody asked for the button#

Because there was a workaround, and the workaround worked.

Somebody knew how to make the number look right again. It took a few minutes, it involved a second entry and a note, and it was taught to the next person who needed it. Within a few months it was simply how a wrong receipt gets fixed here. The gap had not closed. It had been staffed.

Nobody files a request for something they have already learned to live without. That is not a failure of the people; it is what competent people do with an obstacle. They route around it, and the routing becomes invisible, including to them.

Two questions worth asking of your own tools#

The first: what has been built here that nothing calls? Not as an audit exercise — as a search for things somebody once thought were needed, and were, and never arrived. Half-finished work does not announce itself, because from the outside it looks exactly like work that was never started.

The second, and it is better: what does everybody in this room already know how to work around? Ask it out loud, in a meeting, and wait through the pause. The answers do not come as complaints. They come as instructions, delivered helpfully, in the tone of someone explaining how a door has to be lifted before it will close.

It is also the most productive question to ask when somebody is leaving a role, for the reasons in what makes a handover fail. And the reversal described above is a worked example of a rule we hold everywhere: correct by adding, never by overwriting.