“Just make it do exactly what the old one does”
That one sentence has added more months to migrations than any technical problem I have hit. It sounds safe. The trap is the assumption hiding inside it: that someone in the building still knows what the old system actually does. After fifteen years, usually nobody does.
The behaviour is the spec, and that spec includes a decade of edge cases, silent bug workarounds, and one report finance depends on that nobody can explain. So “do exactly what it does” is not a requirement. It is a request to copy behaviour you have never understood, bug for bug, into a stack you own for the next decade.
The real work in modernisation is not rewriting code. It is recovering intent. Why does this discount only fire on Tuesdays. Why is this field truncated at thirty-eight characters. Who decided that, and is it still true.
Archaeology with a deadline
Legacy modernisation gets sold as a porting problem: pick the target, move the code, ship. The target stack is rarely what kills you. A stack is a decision you can argue about in a room. The twenty years of business rules nobody wrote down cannot be argued with. They have to be excavated. You are doing archaeology with a deadline.
It is worth being honest about what that archaeology costs when it is skipped. On one migration a six-month plan stalled three weeks in because a single batch job had no owner: the person who understood it had retired in 2019. A team of eight sat parked while we reverse-engineered what one undocumented mainframe job actually did. That is low six figures of burn to produce nothing. Not the architecture. Not the budget. One job nobody could explain. That is the bill for treating intent as something you can pick up on the way past.
How we recover it, in order
The technical playbook for this is not mine and not new (Michael Feathers wrote most of it in 2004), but it works, in this order.
-
Wrap the legacy in characterisation tests, so we can diff old behaviour against new, byte for byte, before changing a line. “Correct” means identical output, weird edge cases included.
-
Interview the people who consume the outputs, not just the ones who wrote the code. The Tuesday discount lives in someone’s head, not the repo. This is the step vendors skip, and it is the one that finds the clerk’s Friday spreadsheet that turns out to be the real system of record.
-
Reconstruct the decisions as short ADRs, so the next team inherits the why, not just the what.
On a recent manufacturing ERP migration, that pass paid for itself before we shipped a single new feature. Roughly a third of the legacy logic turned out to be dead or obsolete: branches that never executed, workarounds for a system retired years earlier, rules nobody left in the company could explain. The client was relieved we had not faithfully reproduced it.
The part the tests never tell you
One honest caveat: in banking, insurance, and pharma, “do exactly what it does” is sometimes a regulatory requirement, not naivety. Even then you do not get to skip this step. You cannot prove equivalence to an auditor until you can state, precisely, what the old system does.
And there is a part the characterisation tests never tell you. They tell you what the system does. They never tell you who needed it to stay opaque. Someone usually benefits from the old system staying mysterious; being the only person who understands it is their leverage. Making the mystery legible can feel like a threat, and if you skip that conversation early it comes back as quiet non-cooperation in month four. That is a conversation, not a Jira ticket.
So on your last migration, did you budget time to recover intent up front, or did you scope it as a like-for-like rebuild and meet the why the hard way? If you are scoping one now and the plan says “replicate existing behaviour”, that line is where the months hide. Talk to TrueForge and we will help you cost the excavation before it costs you.