Migration Archaeology

Every large enterprise has a system that works, that nobody fully understands, and that somebody proposes replacing roughly every three years.

The proposals are usually reasonable. The estimates are usually wrong by a wide margin, and they are wrong for a consistent reason: the team estimated the visible system and inherited the invisible one.

A legacy system is not undocumented. It is documented in behavior, in the corrections people build around it, and in decisions whose authors have retired. Reading that record is a discipline, and it belongs before the estimate, not after the contract.

The documentation is the worst source and everyone starts there

There are four places to learn what a system does, and their reliability runs almost exactly opposite to how often people consult them.

Observed behavior is the ground truth. What the system does in production, under real volume, with real data, including the paths that only fire at quarter end and the one that only fires for a single country. Nothing overrides this. If behavior and documentation disagree, the documentation is a historical artifact.

The corrections people make around it are the second source, and the most underused. Every spreadsheet maintained beside the system, every manual step in a runbook, every "just remember to check this before you post" is a defect report that was never filed. Map those and you have mapped the gap between what the system does and what the business needs, which is precisely the gap the replacement has to close and precisely what the requirements document will omit.

The code and its history tells you what was intended, which is not the same as what happens. It also contains intentions that were abandoned midway, which is why systems accumulate structures that are referenced nowhere and deleted by nobody. Commit history and change records, where they survive, are the closest thing to an interview with people who have left.

The written documentation was accurate on the day it was written. It has since described a system that no longer exists, with increasing confidence, because nothing corrects it.

Most migrations begin at the fourth source and stop there, which is how a program discovers in user acceptance testing that a quietly critical behavior was never in scope.

Chesterton's fence, and the version of it that actually applies

The classic rule says do not remove a fence until you know why it was put there. In enterprise systems the useful version is sharper, because the fences are numerous and most of their builders are gone.

The strange thing in the system is one of four things, and the whole job is telling them apart.

It is a regulatory or contractual requirement, in which case removing it is not a simplification, it is an exposure. These are the most dangerous to clean up because they usually look arbitrary. A field that must be retained for a specific number of years, a sequence that must never have gaps, a rounding rule that seems wrong and is legally specified.

It is a workaround for a defect in another system, which may or may not still exist. Worth checking, because if the upstream defect was fixed six years ago you are carrying a scar for nothing, and if it was not, you are about to reintroduce a problem somebody already solved.

It is an accommodation for a customer, a plant, or a country that is still operating on the assumption it exists. These break loudly and at the worst time, because the affected party is outside your change program and was never asked.

Or it is genuinely obsolete, a fossil from a process that ended. This is the only one you can delete freely, and it is a smaller share of the total than any modernization plan assumes.

You cannot tell which is which by reading the code. You tell by finding who depends on the behavior, and that is fieldwork rather than analysis.

The method

Start from the outputs, not the code. Every report, file, feed, and document the system produces has a consumer, and the consumer can tell you which parts they actually use. This is the fastest way to find both the critical path and the large amount of the system that produces things nobody has read in years.

Follow the corrections. Ask each team what they fix by hand and what they check before trusting it. You will learn more about the true requirements in a handful of these conversations than from any specification, and you will find the workarounds that need to become features rather than being migrated as-is.

Interview the leavers while they are still reachable. The person who is retiring in four months is the single most valuable and most perishable asset in a modernization program. Book the time. Ask why, not how, because the how is recoverable from the system and the why is not.

Instrument before you rewrite. Where you can, log which paths actually execute. Dead code is much easier to retire with evidence than with argument, and the evidence also protects you when somebody insists a path is critical that has not run in two years.

Write the fence register. A living list: the strangeness, what you currently believe explains it, the confidence, and who could confirm. It converts the scariest part of the program from folklore into a tracked list, which is also what makes it possible to hand off.

Where this goes wrong

The most common failure is treating the old system's behavior as the specification. That produces a faithful reimplementation of forty years of accumulated compromise, at modern cost, and it is how you spend a large budget to arrive where you started with a newer logo.

The opposite failure is treating it as noise, declaring a clean-slate design, and rediscovering each fence in production, one incident at a time, in the order of how badly each one hurts.

The method above sits between them, and the deliverable is judgment rather than a document: knowing which of the four categories each piece of strangeness belongs to, and having evidence rather than an opinion.

The part that is genuinely uncomfortable

Nobody wants to fund archaeology. It produces no demo, it lengthens the visible timeline, and it makes the program look slower than the one being pitched by whoever has not done it.

But the work is not optional, only its timing is. You will either read the system before you replace it, on a schedule you chose, or you will read it afterward, in production, on a schedule chosen by whichever fence you knocked down first.