Recovering what the business meant
A Socratic walk-through of recovering what the business meant — reasoned out one step at a time, not lectured.
The question we started with
THE QUESTION #How do you work out what a rule was for when all that survives is the code that enforces it?
A routine rejects any application where the applicant's age is under 21 and the requested term exceeds 180 months, unless a flag on the branch record is set. Nobody knows why. The author retired, the requirements document does not mention it, and the branch flag is set for eleven branches out of four hundred.
The code is completely unambiguous about what happens. It is entirely silent about why, and that silence is not an accident of poor documentation — it is structural. Executable code records a decision's outcome, never its justification. So what could possibly recover the reason, and how confident are we entitled to be?
Reasoning it through
REASONING #Start with the logical shape of the problem, because it sets the ceiling on everything after. Many different intentions produce identical code. A risk policy, a regulatory ceiling, a reinsurance treaty limit, a workaround for a downstream system that overflows, and a defect that was never noticed can all compile to the same three lines. Recovery therefore runs backwards from effect to cause — inference to the best explanation, not deduction — and inference to the best explanation can be wrong even when every step is careful. That is worth holding onto, because the register of a recovered rule tends to sound more settled than the evidence supports.
Given that, what evidence is available? Rank it by how hard it is to fake.
Literal constants are the strongest and the most underused. A number in code often points at something outside the code that can be checked independently. A rate matching a published statutory figure, a threshold matching a regulator's published limit, a date matching the commencement of an act — these are anchors, because the world has a record of them. If the 180 months coincides with a maximum term named in a lending code of practice, that is not a guess any more; it is a match against an external fact, and it can be dated.
Next, structural evidence. Where a rule sits, what it is grouped with, and what it does on failure all carry information. A check that raises a specific rejection reason routed to a compliance queue is a different animal from one that silently adjusts a value. Exception handling in particular tends to preserve intent, because the error text was written for a human.
Then the softer sources: identifiers, comments, version-control history, defect tickets, and the memories of people who used the system. All are useful and all drift. A comment describes the code as it was when written; a name survives the refactor that changed the meaning underneath it. Treat these as leads that direct where to look, not as findings.
And there is a source that is easy to forget: the data. If the flag is set for eleven branches, look at what those eleven have in common. Same region? Same acquisition? Same date of onboarding? A pattern in the population the rule applies to frequently reveals its purpose more directly than anything in the source, because the exception list is a record of who argued successfully to be exempted.
Now the uncomfortable refinement. Suppose you succeed and establish that the rule was a defect — a comparison written the wrong way round in 1998. Does it follow that it should be removed? Not automatically. Downstream, twenty-eight years of behaviour has been observed and adapted to: reports reconcile to it, a partner's file format assumes it, staff have a workaround. The observed behaviour has become a requirement independent of its origin, which is the practical content of Hyrum's law — with enough users, every observable behaviour of a system is depended upon by somebody. So original intent and current obligation are two separate findings, and conflating them is how a correct fix causes an outage.
Which gives the honest output: not a sentence saying what the rule means, but a hypothesis, its supporting evidence, its confidence, and a separate note on whether current behaviour is load-bearing regardless.
The analogy
THE ANALOGY #Reading a will that names an unusual bequest with no explanation. You can establish exactly what it instructs; that part is written down and enforceable. Why the testator chose it has to be reconstructed from letters, dates, who else was in the family at the time, and what the law allowed that year — and two coherent stories may fit everything you can find. The instruction remains binding whichever story is true, which is precisely why executors act on the text while historians argue about the motive.
a will is fixed at a moment, whereas code is amended by many hands over decades, so a rule can be a composite whose parts had different reasons and whose current form no single person ever intended.
Clarifying the model
THE MODEL #Three refinements.
First, distinguish the essential from the incidental. Some of what the code does is the business rule; some is an accommodation to the machine of the day — a field width, a two-digit year, a batch-size limit, an ordering imposed by a file structure. Carrying an incidental constraint into a new system as though it were policy is one of the most common and most expensive migration errors, and telling the two apart is most of the work.
Second, confidence should be expressed as evidence rather than as a word. "Probably a regulatory limit" is nearly useless a year later. "Matches the 180-month ceiling in the 1997 lending code; the check was added in the same quarter; eleven exempt branches all joined after 2004" is reusable, and lets the next reader disagree with the conclusion while keeping the facts.
Third, the vocabulary matters as much as the rule. Recovering that a field called STAT-CD-3 is what the business calls a forbearance state changes every later conversation about it. Domain-language recovery is not decoration — it is what lets the people who know the business check your work, and they are the only reliable oracle available.
A picture of it
THE PICTURE #How to reada rule moves between states of belief, not states of execution. Enumerating several candidate explanations before testing any is the step most often skipped, and it is what keeps the first plausible story from becoming the answer. Refutation loops back rather than terminating, because ruling one explanation out is progress. The two exits are the important part: a rule can leave as understood, or it can leave as merely obligatory — the lower path shows that a rule whose intent is never recovered can still be a firm requirement, because something downstream now depends on the behaviour.
What became clearer
WHAT CLEARED #Code is an under-determined record: many intentions collapse to the same instructions, so recovery is abductive and its output is a dated hypothesis with its evidence attached, not a fact. The strongest evidence is whatever points outside the code — a constant matching a published figure, a date matching a statute, a pattern in who was exempted. And the separate, easily missed finding is that current behaviour can be obligatory whatever its origin, so establishing that a rule was a mistake is the beginning of the decision rather than the end of it.
Where to go next
ONWARD #- How to tell an essential business constraint from an accommodation to obsolete hardware.
- What makes a recovered rule verifiable by a domain expert who cannot read the code.
- How to record a hypothesis so a later reader can overturn the conclusion without losing the evidence.
Key terms
TERMS #| Term | What it means |
|---|---|
| Abduction | inference to the best explanation, which yields plausible rather than certain conclusions. |
| Domain-language recovery | restoring the business vocabulary that a system's identifiers obscure. |
| Hyrum's law | the observation that with enough users, every observable behaviour of a system is depended upon by someone. |
| Incidental constraint | a limit imposed by the implementation of the day rather than by policy. |
| Magic constant | an unexplained literal value, often an anchor to a fact recorded outside the system. |
Every term the collection defines is gathered in the glossary.