Software replaces the memory of why

Somewhere in almost every reporting estate I have looked at, there is a filter that excludes a category of records, and nobody currently employed can say why it is there.

The rule runs. It has run every night for years. It is correct, in the sense that it does exactly what it was written to do, and the output has been reviewed and signed and used for decisions the entire time. What has gone is the sentence that would explain it, and the sentence went years before anybody needed it.

I used to treat that as an artefact of bad hygiene, the kind of thing that happens to organisations that do not document. I no longer think that. I think it is a structural property of encoding a rule at all.

The asymmetry

An organisation’s memory has two parts: what it does, and why it does it. Those two parts decay at wildly different rates and the difference is not accidental.

The behaviour is executed. Every night it runs, it is refreshed, tested against reality, and repaired the moment it breaks. It has a maintenance mechanism built into its existence: if it stops working, somebody notices immediately.

The reason is not executed. Nothing consumes it. Nothing breaks when it goes stale. It lives in the heads of a few people and in a comment nobody reads, and its only preservation mechanism is that somebody happens to remember and happens to be asked. Both of those fail quietly and neither failure produces an alarm.

So over a decade, the behaviour is at full fidelity and the reason is at zero. Not degraded, gone, because reasons do not degrade gracefully. Either you can state the condition the rule was responding to or you cannot.

Why this is worse than losing both

Here is the part that took me a while.

If a process is carried in a person’s head and the person leaves, the whole thing goes, and that is a visible loss. Somebody has to rebuild it. The rebuilding is expensive and slow and it has one enormous compensating property: in the course of it, the question gets asked again. What is this for. Does the condition still hold. Somebody has to reason about the situation as it is now, which is often not the situation the rule was written for.

When the behaviour survives, that never happens. There is no trigger. The report runs, the number appears, the number is used, and at no point does the system generate an occasion on which anyone has to justify the rule. It has been converted from a decision into a fact about the environment, and you do not interrogate facts about the environment.

The rule outlives its condition and there is no mechanism anywhere that would notice. That is the whole problem in one sentence. A migration is the only event I know of that reliably surfaces it, and it surfaces it in the worst possible form, as a hundred small decisions somebody has to make about logic they did not write, on a deadline, with no one to ask.

I did this myself

At my last accounting role I automated reconciliation and a chunk of the payroll reporting, and cut the reporting cycle by about a fifth. It was good work. I would do it again.

I encoded my own judgements in it. Several small ones, about what to match and what to treat as an exception and where the boundaries sat, and every one of those judgements was based on something I knew at the time about those particular books. I did not write any of it down, and the reason I did not is not laziness. It is that at the moment of encoding, the reason is obvious. Obvious things do not feel like they need recording. That feeling is the whole trap, because the reason is obvious to exactly the person who is never going to need it explained.

Documentation is the standard answer and it is a weak one. A comment does not execute. Nothing forces it to stay true, so it drifts out of agreement with the code and becomes a wrong explanation, which is worse than none, because a wrong explanation stops the next person from asking.

I do not have a fix. The closest I have got is to write down, next to the rule, not what it does but what would have to change for it to be wrong. That is a sentence with a trigger in it. It is the only kind I have seen survive.