Every company has one: the system nobody wants to touch, that nobody fully understands anymore, that still runs a piece of the business nobody's willing to risk breaking. It's usually old, often ugly, and frequently the single most business-critical piece of software in the building, precisely because it's absorbed twenty years of edge cases that were never written down anywhere else.
Retiring it isn't just a migration project. It's a knowledge-extraction project wearing a migration project's clothes, and treating it as purely technical is how companies lose things they didn't know they were about to lose.
Why legacy systems accumulate knowledge nobody documented
A system that's been in production for a decade or more has absorbed a huge number of small decisions: a tax rule that only applies to three specific states, a customer discount logic that exists because of a single contract negotiated years ago, a validation step added after a very specific and very expensive incident nobody wants to repeat. None of these are documented anywhere except as code, because the person who added them moved on, and the reason behind the logic left with them.
This is the real risk in any legacy system retirement. The system's replacement will faithfully reproduce whatever's in the specification, and the specification is usually "what the old system currently does," reconstructed by reading code that was never meant to be read as documentation. Anything subtle that got missed in that reconstruction doesn't fail loudly. It fails quietly, months later, when an edge case the old system handled correctly produces a wrong answer in the new one.
Photo by Czapp Árpád on Pexels
Start with an audit, not a migration plan
Before writing a line of replacement code, the highest-value work is figuring out what the old system actually does, as opposed to what anyone remembers it doing. This means:
Interviewing everyone who still touches it, even peripherally. Support staff who field tickets about it, finance people who pull reports from it, the one engineer who's patched it twice in the last five years. Each of them holds a different fragment of institutional knowledge, and none of them individually has the whole picture.
Reading the actual code for business logic, not just architecture. The interesting parts of a legacy system are rarely in its overall structure. They're buried in conditionals: the "if customer type is X and date is before Y, apply this exception" lines that encode a decision someone made once and never wrote down anywhere else.
Cataloging every integration point, documented or not. Legacy systems frequently have quiet, undocumented dependents: a nightly export a different team scripted against years ago, a report a stakeholder pulls manually every quarter. Decommissioning the source system without finding these first breaks something for someone who had no idea they were depending on a system that was "being retired."
Photo by RDNE Stock project on Pexels
Prioritizing what to extract first
Not every undocumented rule carries equal risk, and a full audit of a large legacy system can easily balloon into a project of its own if every discovered quirk gets the same level of scrutiny. A useful triage: rank each discovered rule by how often it fires (a rule that runs on every transaction matters more than one that fires once a year) and by how expensive a wrong answer would be (a pricing or tax rule that's wrong is more costly than a cosmetic formatting quirk). Spend the deepest investigation time on rules that are both frequent and expensive to get wrong, and accept a lighter touch on rules that are rare and low-stakes even if they never get fully explained.
This triage step is also where it's worth being honest about timeline pressure. A full audit of a genuinely old, genuinely large system can take longer than stakeholders expect, and compressing it to fit an arbitrary deadline is how the highest-risk rules end up under-investigated instead of the lowest-risk ones.
Where the expertise actually shows up in a retirement project
"The failure mode I see most often isn't a bad migration. It's a good migration of an incomplete specification, because nobody budgeted time to actually extract what the old system knew before replacing it." - Dennis Traina, founder of 137Foundry
This is the part of a legacy modernization project that's easiest to underbudget, because it doesn't look like engineering work in the traditional sense. Interviewing six people about tribal knowledge and reading old code for undocumented business rules feels slower and less concrete than writing new code, which is exactly why it's the part most often compressed under deadline pressure, and exactly the part whose gaps show up as production incidents six months after the "successful" migration.
Building a decision record as you go
Photo by Pavel Danilyuk on Pexels
As the audit surfaces undocumented rules and edge cases, write each one down as a short, dated decision record: what the rule is, why it seems to exist (even if that's a guess), and whether it's still relevant to the business today. Not every quirk in a legacy system deserves to be preserved. Some of it is genuinely dead logic left over from a business rule that no longer applies, and the retirement project is a legitimate opportunity to retire that logic too, deliberately, rather than by accident.
The difference between "we chose not to carry this rule forward" and "we didn't know this rule existed" is the entire point of doing the audit first. One is a decision. The other is a gap that surfaces as a bug report from a confused customer or an auditor.
Running the old and new systems in parallel
For anything genuinely business-critical, run the replacement alongside the legacy system for a defined period, feeding both the same inputs and comparing outputs. Discrepancies surface exactly the edge cases the audit might have missed, while there's still a working legacy system to consult for the correct answer. Once the legacy system is fully decommissioned, that safety net disappears, and any gap discovered afterward has to be solved from institutional memory alone, which is the very resource this whole process was supposed to protect.
The parallel-run period doesn't need to be indefinite. A month or a quarter, depending on how much of the business cycle the system touches (a system involved in quarterly reporting needs to see at least one full quarter), is usually enough to surface the discrepancies that matter.
Photo by panumas nikhomkhai on Pexels
Assigning an owner to the knowledge, not just the migration
Migration projects usually have a clear technical owner. The knowledge-extraction piece often doesn't, because it doesn't map neatly onto a single engineering role. It's worth explicitly assigning someone, whether that's a product manager, a senior engineer, or an outside consultant brought in specifically for this phase, to own the audit and decision record as a deliverable in its own right, with the same accountability as any other project milestone. Without an explicit owner, this work tends to get done partially, by whoever happens to be curious, rather than completely, by someone whose job it is to finish it.
What to preserve even after the system is gone
Once the legacy system is fully retired, a few things are worth keeping around even though the software itself is gone:
- The decision record built during the audit, as a permanent reference for why the new system behaves the way it does.
- A read-only archive or export of the old system's data, in case a historical record needs to be consulted later for a dispute, an audit, or a regulatory request.
- A short written history of what the system did and why it was retired, useful institutional memory the next time someone proposes retiring a different long-lived system and wants a template for how to do it well.
The broader lesson
Legacy system retirement projects fail less often because of bad code and more often because of skipped extraction. The code was never the hard part. The business knowledge embedded in it, undocumented and distributed across people who may not even remember they have it, is the actual asset at risk, and the only way to protect it is treating the audit as a first-class phase of the project rather than a formality on the way to the "real" migration work.
For teams weighing whether to handle a legacy migration internally or bring in outside expertise for the audit and cutover, 137Foundry's data integration service covers exactly this kind of system-to-system knowledge transfer, alongside the broader services 137Foundry offers for technology modernization work. More background on how the underlying decisions get made is on the 137Foundry site directly.
Further reading
- Wikipedia's entry on legacy systems covers the general definition and common characteristics.
- Wikipedia's entry on technical debt is useful background on why these systems accumulate undocumented complexity in the first place.
- Wikipedia's entry on knowledge management covers the broader discipline of capturing and preserving organizational knowledge, which is the actual discipline underlying a good legacy retirement project.
- The National Archives publishes guidance on records retention and institutional knowledge preservation that's relevant well beyond government use cases.
- ISO maintains standards, including ones covering records and knowledge management, for organizations that want a formal framework rather than an ad hoc one.
A legacy system's code is replaceable. What it learned over the years, often without anyone writing it down, is not, unless someone deliberately goes looking for it before the system disappears.
