The situation
A manufacturer asked us to take over a 20-year-old order platform. It was business critical, it ran month-end close, and the people who understood it were nearly all gone. Three engineers had ever known it well. Two had retired. The third was on his way out and answered most questions in riddles.
The documentation described version 4. The system that was actually running was closer to version 9: ten years of undocumented patches for edge cases nobody could explain any more. On paper, a straightforward modernisation. In practice, a system whose real behaviour nobody could fully describe.
What was really going on
The most important logic was not in the code at all. A clerk kept an Excel sheet that “fixed” the platform’s output every Friday, before invoicing ran. It corrected for things the system got wrong, things it had been getting wrong for years. Nobody mentioned it, because to them it was not part of the system. It was just Friday.
That spreadsheet was load-bearing and invisible. Had we rewritten the platform from the documentation, we would have shipped something that produced subtly wrong invoices, and we would not have known until the numbers stopped matching the bank. This is the quiet risk in every old system: the rules that keep a business solvent are often the ones that were never written down.
What we did
We refused to read a single line of code as gospel. Instead we pinned behaviour first.
We wrote characterisation tests against the live system, proving what it actually did today, bug for bug, before changing anything. None of this is novel; the methods are decades old and anyone competent uses them. The differentiator is not the technique. It is the artefact you produce and who is made to own it.
We then ran an event-storming session with the people who actually run the flow, the Friday clerk included, not the architect who left in 2014. And we hunted the shadow system on purpose: every spreadsheet, manual workaround and orphaned scheduled job was treated as in scope until proven otherwise.
None of that happens without solving the political problem first, which is the part most write-ups skip. You will not get characterisation tests against a live system without sign-off from whoever owns the outage risk. You will not get the Friday clerk in the room if their manager thinks that spreadsheet makes the department look careless. So we secured both access decisions in writing before day one. That, not the tooling, is the real gate.
This is how we approach legacy modernisation: understand the running system honestly before touching it, and make the keep-or-kill decisions explicit rather than accidental.
What changed
The deliverable was not a diagram. It was a list of behaviours the live system had that nobody could justify: keep, kill or escalate, one decision each. The client signed that list.
That signature was the whole point. It moved the keep-or-kill call onto the people who carry the business risk, and it stopped the modernisation from quietly dropping the one rule that kept the month-end numbers right. The Friday spreadsheet did not survive as a spreadsheet, but every rule inside it was found, examined and either rebuilt into the system or deliberately retired with someone’s name against the decision.
The numbers here are openly estimated rather than audit-grade: the value was not a cost saving on a line item, it was a rewrite that did not silently break invoicing. The cost of getting that wrong, on a system that runs month-end close, is the kind of figure nobody wants to discover after go-live.
If you are about to modernise something old and load-bearing, the first question is not which stack. It is: who actually knows how this works, and what is the plan for the day they leave? If that question makes you uneasy, talk to us before the rewrite, not after.