The Legacy System Dossier
Before rewriting anything, understand what the system really does.
A fixed-scope, read-only assessment of one business-critical system. Nothing is modified. CodeLead maps the architecture, lifts the business rules out of the code, traces what depends on what, and ranks the risks, so the modernization plan starts from evidence instead of hope.
In three to four weeks you will know
- What the system actually does
- Where the business rules live, down to the line of code
- What depends on it, and who breaks if it moves
- What could break, and how badly
- Who holds the knowledge the code never wrote down
- What to modernize first, and in what order
Why now
Standing still is the expensive option. So is the usual way of moving.
Almost nobody delays modernization because their system is fine: in one industry survey, only about one in twenty leaders said their current platform was adequate. They wait because the project itself is frightening, and the fear is rational. Studies put the failure rate of modernization programs between 70 and 79 percent, counting projects that blew their budget, missed their goals, or were abandoned outright.
Meanwhile the bill for waiting compounds. Legacy maintenance costs rise an estimated 10 to 25 percent a year as specialists retire and vendors sunset support, and most of the engineering budget goes to keeping the old system alive instead of escaping it.
Figures from third-party research, collected with sources in the research brief below.
- 70–79%of modernization projects miss goals, blow budgets, or are abandoned
- 60–80%of enterprise IT budgets go to legacy maintenance (Gartner, Forrester, Deloitte benchmarks)
- 10–25%annual growth in legacy maintenance cost as talent retires and support ends
- ~60%of breaches linked to outdated or unpatched systems (IBM Cost of a Data Breach, 2025)
Why projects stall, and what the Dossier does about each
| What kills projects | How it shows up | What CodeLead does first |
|---|---|---|
| Undocumented business logic | Decades of rules buried in code with no one left who understands them. Extraction failures surface as broken edge cases at cutover, or as the mid-project discovery that the rules can't be safely extracted at all. | The survey lifts the rules from code with file and line before anything moves, flags the ones enforced two ways, and books interviews with the authors while they are still reachable. |
| Scope set by the old system | Teams faithfully rebuild every legacy feature, including the share nobody uses, and the budget inflates to match. | The contracts catalogue and history intelligence show what is actually called, what changes together, and what has not been touched in a decade, so scope is a decision, not an inheritance. |
| Late testing | Testing bolted on at the end exposes data and behavior differences during cutover, often triggering rollback or abandonment. | What must not break is locked in with tests before anything changes, and every increment proves it still behaves the same. Nothing is marked done that wasn't machine-checked. |
| The dual-run trap | Running old and new in parallel costs about 14 percent more per year during the transition. Cost rises for years before savings appear, and executive patience runs out first. | The migration sequence moves modules in dependency order, in small verified increments, so each wave retires part of the old system rather than the whole program waiting on a big-bang cutover. |
| Talent shortage | Few people understand both the legacy stack and the target architecture, and the ones who understand the legacy side are retiring. | Tribal knowledge is captured into a living map of the system, where facts are separated from guesses, so it survives the people, and the tooling carries the mechanical work. |
| Tactical firefighting | Under pressure, teams abandon the plan and hardcode quick features on the new platform, building a new legacy system before the old one is retired. | Every change passes the same hard safety checks and leaves an evidence record, on the old code and the new. The discipline does not relax when the deadline gets close. |
The successful minority in the research share a pattern: phased approaches over big-bang rewrites, scope set by business need rather than feature parity, honest accounting for the transition cost, and testing that starts before the change. That pattern is the Dossier's method.
Step one
The Legacy System Dossier
A read-only, fixed-fee assessment of one legacy system. Nothing is modified. CodeLead runs inside your environment or on a machine you control, and every action is logged.
In three to four weeks you know what the system is, what it depends on, which rules are hiding in it, what can be locked in and migrated safely, and in what order, with evidence for every claim. The questions you need answered are agreed in writing before we start, and each one is answered in the Dossier with the evidence behind it.
What makes it different from a slide deck
- A receipt for every recommendation: each figure traces to a scan, a log, a commit, or an attributed interview
- Each section is labeled Automated Partial or Manual, so you know what the tool measured and what a person judged
- Rules lifted from code are marked Inferred: they state what the code does, not why
- What the survey cannot see is marked as an assumption to confirm, never quietly filled in
- The same survey re-runs after each phase, so "after" evidence is in the same format as "before"
What you receive
- System inventory and architecture map
- Repositories, projects, modules, entry points, layering, and the call and dependency graph, with a one-page architecture narrative.
- Dependency and integration map
- Public API surface, database dependencies, external services, queues, file interfaces, scheduled jobs, and who breaks if each moves.
- Runtime and package lifecycle risks
- Every package and runtime with version, support status, end-of-support dates, known advisories where resolvable, and breaking-change exposure on upgrade.
- History intelligence
- Hot files, co-change clusters (files that always change together), knowledge concentration by author, churn trends.
- Business-rule and tribal-knowledge inventory
- Rules embedded in code and comments (validation, pricing, workflow states, thresholds, magic numbers) with file and line, conflicts between comment and code, plus attributed testimony from your veterans.
- Testability map
- Per area: what tests exist, what "green" actually verifies, how tangled the I/O is, and an honest judgment of how tightly current behavior can be locked in before any change.
- Migration-risk register
- Not a style review. Only what stands between you and a safe change: shared state, blocking calls, hidden dependencies, swallowed errors, and methods too long to test on their own.
- Modernization options
- Twelve modernization types, from an in-place upgrade to retire-and-replace, assessed against your system and your stated goals. Each is graded as a fit, as possible but not indicated, or as not assessable from code, with what would change that answer, what it changes and preserves, its risks and preconditions, and an estimate with its basis and its confidence. The rewrite is priced next to the incremental path, so the choice is visible.
- Migration sequence and phased plan
- Which modules can move in isolation, which are coupled, a proposed sequence of waves, and an exit criterion and proof step for every phase.
- Evidence appendix
- Every claim traced to its artifact, with an explicit automated-versus-manual label for each section and a stated confidence boundary.
- A living map of the system
- A knowledge base seeded with all of the above, where facts are separated from guesses: each entry says whether it was verified from code, inferred, or given as testimony. It stays with you.
How the engagement runs
-
Scoping call
Twenty minutes with whoever knows the system best. We agree on the one system, the questions you need answered, the success criteria, and which machine the survey runs on, in writing, before we start.
-
Read-only access, inside your environment
CodeLead runs on a machine you control, under NDA. It reads; it never writes. Every action is logged to a file you keep. Running models locally needs real hardware, so the machine is specified at the scoping call rather than discovered later. It is one workstation, not infrastructure: the build in our case study ran on a single laptop. It can be yours or one of ours, used under the same terms.
-
Survey, analysis, and interviews
Two to three weeks of tool-driven extraction, then conversations with the engineers who carry the tribal knowledge. Their testimony goes into the Dossier, attributed, and their "why" is attached to the rules the code only states.
-
Delivery and walkthrough
The written Dossier, an executive brief for the CTO and architects, the evidence appendix, and the knowledge base, walked through with your team. You keep everything.
Terms
- Fixed fee, quoted after the scoping call.
- Success criteria agreed in writing before work starts, and each one answered in the Dossier with the evidence behind it.
- Read-only throughout; no changes to your repository, environment, or process.
- Each section of the Dossier states what was automated and what was done by hand.
- Founding-customer terms for the first engagements, in exchange for a reference and case-study rights.
Stacks
.NET Framework, ASP.NET WebForms, VB.NET, and VB6-era systems first; Java and older Spring next. COBOL and mainframe cores are handled with a partner; the .NET estate around them is in scope.
What you keep
You stop guessing. You start deciding.
Even if you do not start a modernization project straight away, the Dossier leaves your team with durable assets, and they are yours whether or not you ever work with us again.
- A map of the architecture and its dependencies
- A record of the business rules, each with its source
- A risk-ranked modernization roadmap
- A validation strategy for every phase
- A living map of the system your team keeps using
- Evidence behind every major claim
After the Dossier
Modernization, one verified increment at a time
Pilot slice
One module from the first wave of the migration sequence. What it does today is locked in with tests, the change is made in small checked increments, and the result is proven to behave the same. You get the migrated module, the proof, and an exported evidence pack.
Program delivery
The migration sequence, executed. Each wave has the same shape: clear what blocks testing, lock in current behavior, make the change, prove it still behaves the same, and re-run the survey. Every change is a readable commit with its evidence record, and nothing is marked done that wasn't machine-checked.
The model proposes. CodeLead checks. Humans decide. People approve the goal, the plan, the scope of each change, and anything that touches dependencies or data, or cannot be undone, before it lands.
Day two
The migration ends. The system still has to be changed on a Tuesday.
Modernization is rarely put off because the migration looks hard. It is put off because of a quieter suspicion: that in five years you will be standing exactly here again.
The suspicion is well founded, and the mechanism is documented. Under deadline pressure, teams abandon the plan and hardcode onto the new platform, building the next legacy system before the old one has finished being retired. A migration that ends at the cutover has bought you a few years, not a different situation.
Most engagements end there, and the tooling leaves with the vendor. This one ends with the things that make the next change provable. They live in your repository and they are yours whether or not you ever work with us again.
What stays with you
- The tests that lock in behavior. Written before anything was changed, and left in your source control. In the sample portfolio no test reached any of the nine legacy areas. Afterwards, "did I break anything?" becomes "the tests are green."
- The living map of the system. Every entry carries a trust level and its citation, so a verified command and a chat rumor are visibly different kinds of knowledge. The reasoning your veterans hold, written down while they are still reachable.
- The evidence records. Requirement to change to check to validation to approval, per increment. The trail an auditor, an acquirer, or your next architect asks for, six months after anyone remembers the details.
- The survey, re-runnable. The same read-only survey that produced the Dossier runs again whenever you want, so drift arrives as a diff against a known baseline: a new test desert, a runtime that has left support, an advisory published last month.
What it deliberately does not do is change your system on its own. Every proposal passes the same hard safety checks and still waits for a person to approve it. A maintenance engine that applies its own patches unattended is just a faster route back to where you started.
Downloads
Read the sample Dossier and the research.
The full Meridian Dossier and its executive brief show exactly what you receive. The research brief collects the spend, cost-of-waiting, and failure figures cited on this page, with sources.
- Meridian Legacy Systems Portfolio Dossier The full engineering Dossier for the sample portfolio: three real .NET code bases surveyed read-only, with every figure traced to a survey artifact and each section labeled by provenance.
- Meridian Portfolio Executive Brief The short version for a CTO and lead architects, produced from the same artifacts: the decision, the three findings, the calendar, and the funding request.
- Application Modernization: Spend, the Cost of Waiting, and Why Projects Stall A research brief with sources: what companies spend on modernization, what standing still costs, the six ways projects die mid-flight, and what the payoff looks like for the ones that finish.
Common questions
Is AI making the decisions?
No. The model proposes. CodeLead checks. Humans decide. AI does the mechanical work inside boundaries your team sets, and people approve the goal, the plan, the scope, and every risky change.
How is this different from a large consultancy or an AI modernization platform?
Three things. Nothing leaves your environment. You keep every artifact, including the living map of the system. And the Dossier states what it could not determine as plainly as what it found.
We can't give an outside tool access to our code.
It runs on a machine you control, no code leaves the building, and the log is yours. The output is a report about your system, not your system.
We already use Copilot or Cursor.
Those generate code. The Dossier tells you what is true about the code you already have, with evidence, and which changes would be safe. Different job; you'll want both.
What do we need to provide?
Read-only access to the repository, a few hours with the engineers who carry the history, and a machine for the survey to run on. Either arrangement works: one of yours, agreed at the scoping call, or one of ours, brought in and used under the same NDA. Local models need real hardware, and a standard-issue corporate laptop is often not enough.
How much of this is automated?
In the sample portfolio, 61% by section weight: five sections fully automated, seven tool-measured and human-judged, two manual. Each section says which. Interviews and the validation strategy are human work the tool informs but does not perform.
Who does the work?
CodeLead does most of it; the founding engineers do the rest and tell you exactly which was which.
We'll do the migration later. No budget now.
The Dossier is valuable on its own. It is the document the acquirer, the auditor, or the new architect will ask for, and it makes any later migration cheaper to scope, with anyone.
Request an assessment
Tell us about the system.
What it does, roughly how old it is, what it's built on, and what's making the question urgent. We reply within one business day with either a scoping call or a one-page proposal.
Prefer to talk first? Book a 20-minute call or email hello@codelead.dev.