We Just Retired a 15-Year-Old System. Here's What Almost Got Lost.
At 137Foundry, we recently wrapped a legacy modernization engagement for a client whose core operations system had been running, largely unchanged in its fundamentals, for fifteen years. It worked. It was also nearly impossible to hire for, since it ran on a stack most engineers under thirty-five had never touched, and every year that passed made the pool of people who understood it smaller.
Here's what almost slipped through, and what we did differently to catch it.
The rule nobody remembered writing
About three weeks into the audit phase, we found a conditional buried in a pricing calculation that applied a specific adjustment for orders shipped to one particular region. Nobody on the current team knew why. The commit that introduced it was over a decade old, with a message that just said "fix pricing bug." No ticket reference, no further explanation.
We eventually tracked down a former employee, now retired, through a mutual connection, who remembered the actual story: a regulatory requirement specific to that region that existed for about two years and was then repealed, but the code that implemented it was never removed because nobody wanted to touch pricing logic without being completely sure it was safe to change.
If we'd migrated without finding this, one of two things would have happened. Either we'd have carried forward a rule that no longer applied to any current regulation, silently overcharging or undercharging customers in that region for no legitimate reason, or we'd have dropped it during a code cleanup and, if the regulation had somehow still been relevant in some edge case we didn't know about, created a compliance gap nobody would have noticed until an audit.
Photo by Tima Miroshnichenko on Pexels
Why we built time for this into the project plan explicitly
This is the part of a legacy migration that's easiest to underbudget, because interviewing people and reading old commit history doesn't look like "real" engineering progress to a client watching a project timeline. We've learned to make the audit phase an explicit, separately budgeted line item rather than folding it into general "planning," specifically because that's the phase that gets compressed first under deadline pressure, and it's the phase where the actual risk lives.
What surprised us most
We expected to find undocumented business logic. We didn't expect how much of it was actively still relevant versus how much was genuinely dead weight left over from rules that no longer applied to the business at all. Roughly a third of what we catalogued during the audit turned out to be safe to simply not carry forward, once we confirmed with the client that the underlying business condition no longer existed. That's not a bad outcome. A migration is a legitimate opportunity to deliberately retire dead logic instead of blindly reproducing everything, as long as the decision to drop something is made consciously rather than by accident.
The part the client's leadership didn't expect
Going into the engagement, the client's leadership expected the risky part of the project to be the technical rewrite itself, the part their engineering team was most nervous about. By the end, everyone involved agreed the actual risk had been in the parts that didn't look technical at all: finding the retired employee, confirming which of the thirty-some undocumented quirks we catalogued were still relevant, and deciding, with the client's business stakeholders rather than unilaterally, which pieces of dead logic were genuinely safe to leave behind.
That's a useful thing to set expectations around at the start of any similar project. The engineering work is usually the predictable part. The knowledge-recovery work is where the actual surprises live, and building schedule slack around it rather than around the coding phase tends to produce a much smoother project overall.
Where this fits into how we work
We treat legacy retirement as a knowledge-extraction project first and a technical migration second, because the technical part is genuinely the easier half once you actually know what you're building toward. The full framework we use for this kind of work covers the audit process, the prioritization, and the parallel-run verification period we run before any legacy system actually gets decommissioned.
Further reading
Wikipedia's entry on legacy systems if you want the general background on why these systems accumulate this kind of undocumented complexity in the first place.
Wikipedia's entry on tacit knowledge covers the concept underlying most of what a good audit is trying to recover, knowledge that exists in people's heads and was never written down.
The National Archives has genuinely useful guidance on institutional memory capture, written for government records but applicable to any organization sitting on decades of undocumented decisions.
If your team is looking at a similarly long-lived system and dreading the migration, the technical rewrite usually isn't the scary part. Finding out what the old system actually knew, before it's gone for good, is.
One more thing we'd tell a team starting this today
If we could give one piece of advice to a team about to start a similar project, it would be this: don't wait until the audit surfaces a mystery to start treating former employees as a resource. Build the habit of maintaining some kind of contact, even a light one, with people who've left after long tenures on business-critical systems. The twenty-minute call that solved our pricing mystery only happened because someone on the client's team still had a personal connection to that former employee. A team without that connection would have had a genuinely unsolvable gap in the historical record instead of a phone call away from an answer.
It's a small thing to build into a company's normal offboarding process: a brief, friendly note that it's fine to reach out if a question ever comes up about a system someone used to own. Most departing employees would rather answer one good question years later than watch, from a distance, as something they built gets replaced badly because nobody thought to ask.
It costs almost nothing to set up and it's the kind of thing that only pays off occasionally, but when it does, it can be the difference between a resolved mystery and a permanent, expensive gap in institutional memory.
Why we're writing this up publicly
We don't usually share client-specific project details, and we've kept this one deliberately general (no client name, no identifying specifics about the industry or the exact rule involved), but the pattern itself is common enough, and useful enough for other teams facing a similar decision, that it felt worth writing up. If you're staring down a legacy system that's been running quietly for a decade or more and dreading the eventual replacement project, the lesson here generalizes well beyond our specific client: budget real time for finding out what the system knows before you decide what its replacement should do. It's a small shift in planning that pays for itself the first time it catches something like our pricing mystery before it ships instead of months after, once real customers have already been affected by it.
