It's not the code. It's the context behind it.
Most mainframe migration projects focus on the wrong risk.
Teams spend months analysing code complexity, mapping dependencies, counting lines, categorising programs by size and coupling. They build migration readiness scores. They run static analysis tools. They produce reports showing which programs are "ready to migrate" and which need refactoring first.
Then they migrate something that looked clean, and discover in production that it was quietly wrong for a decade, and nobody knew.
A COBOL program accumulates business rule changes over thirty years. The original requirements document was written in 1994. The last five people who understood why a particular calculation works the way it does retired between 2015 and 2022. The program hasn't been touched since 2018. It runs every night and produces output that downstream systems consume. Nobody questions it.
It looks clean. The code flows make sense. The dependencies are manageable. The logic is traceable.
But somewhere inside it is a 40-line paragraph with three conditions that encodes a regulatory rule from a 2009 compliance requirement. There is no comment. There is no documentation. The Jira project that implemented it was deleted when the team moved to a new system. The developer who wrote it left in 2014.
Everyone assumes it works. Nobody knows why it works. It may have been correct when it was written and quietly wrong for several years.
This is the pattern that makes experienced mainframe professionals nervous about migration projects: not the complex code, but the deceptively simple code. The code that is too small to warrant attention, too old to have living documentation, and too critical to get wrong.
The recent wave of AI-assisted documentation tools, general-purpose LLMs applied to COBOL codebases, addresses part of the problem but not the most important part.
A general-purpose language model can read a COBOL paragraph and summarise what it does syntactically. It can identify that a MOVE statement inside a nested EVALUATE assigns a value to a field. What it cannot do is know that this particular MOVE implements a Basel III capital adequacy calculation that was mandated by a 2010 regulatory requirement, that the specific threshold value in the condition was set by a legal agreement with a regulator, and that changing it by even one basis point would create a compliance violation.
That context does not live in the code. It never did. It lived in the heads of people who are no longer there, in emails that were deleted, in meeting notes that were never written, in a Jira project that was archived and then purged.
The tools that try to reconstruct this context from code alone are solving a hard problem with an incomplete set of inputs. They can be useful for the easy cases, the code that is genuinely self-documenting, the programs that implement straightforward logic with no regulatory or business-specific nuance. But on the critical code, where the documentation gaps matter most, they tend to miss exactly the connections that matter.
Token costs compound the frustration. When a tool burns significant resources and still fails to connect the regulatory dots, teams end up creating new documentation just to feed the tool rather than extracting value from what already exists.
The honest answer is that most teams do not handle it well. They fall into one of two patterns.
The first pattern is migration under uncertainty. The project moves forward, the program is migrated, and the gaps in business rule documentation surface in production. Sometimes this is fine, the missing context turns out to be irrelevant to the actual behaviour of the system. Sometimes it is not fine, and the incident that follows is expensive, embarrassing, and occasionally regulatory.
The second pattern is indefinite stalling. The migration project cannot get sign-off because nobody can fully explain the business logic of the critical programs. The technical work is done. The architecture is designed. But the business stakeholders will not approve because the team cannot demonstrate that they understand what they are migrating. The project runs for years.
The teams that handle it well have something the others lack: one or two people who have been in the organisation for twenty or more years and serve as the institutional memory. They can look at a suspicious paragraph and say "that's the calculation we put in after the 2009 regulatory change, here's what it means." When those people leave, the knowledge leaves with them.
One way to reframe the problem is to stop asking "is this code technically ready to migrate" and start asking "do we understand this code well enough to be responsible for what it produces."
These are different questions. A program can be technically simple and business-critical with undocumented rules. A program can be complex and well-understood with decades of documentation. Technical readiness and business understanding are not the same thing, and treating them as equivalent is where migration projects go wrong.
What actually builds confidence is not static analysis of the code, it is understanding which code paths are live, which are business-critical, and which have not executed in years. Runtime behaviour data, abend patterns, transaction frequencies, SMF records, CICS flow analysis, tells you which programs matter and how much. A program that has not executed in three years is a lower-priority documentation problem than a program that executes ten million times a day and produces output that feeds twelve downstream systems.
This is the approach we take with IMUAI, connecting runtime behaviour to code paths, not to solve the documentation problem directly, but to help teams prioritise where the documentation gaps matter most. The goal is not to automate the knowledge recovery, but to focus human attention where it is most needed before something goes wrong.
If you have people in your organisation who have been working with your mainframe systems for twenty or more years, the most valuable thing you can do is structured knowledge capture, not free-form documentation, but targeted interviews focused on the specific programs and business rules that are most critical and least documented.
The questions that matter:
The answers to these questions are more valuable than any static analysis report. They are also more urgent, because the people who can answer them are retiring faster than the migration projects are completing.
The programs that look cleanest in a technical analysis are often the ones with the most undocumented business context. Complexity is visible. Missing context is invisible until something breaks.
Migration projects that only measure technical readiness are measuring the wrong thing. The risk is not in the code. The risk is in the thirty years of decisions that shaped the code and left no trace.
Also worth reading: Is Mainframe Work at Risk of Being Outsourced? · The Quest for the Lost Holy Mainframe Treasure (text adventure)