AI Code Documentation & Reverse Engineering

Part 2 landed on a clear conclusion: of everything AI does in a migration, reading the system is the clearest, strongest yes. This part is that yes in full. Reverse engineering and documentation are the least glamorous words in modernization and the place AI changes the economics most — because the bottleneck they describe is comprehension, and comprehension at scale is exactly what large models are built for.

The reframe worth holding onto: the hard part of modernizing an old system was never writing the new code. It was understanding the old code well enough to know what the new code has to do. AI moves the bottleneck.

The problem: the system is the only honest spec

Every large legacy system arrives with the same documentation problem. The original design docs, if they exist, describe what the system was meant to do years ago. What it actually does today is the accumulation of every change, fix, and workaround since — and most of that was never written down anywhere except the source. The people who remember why a given routine behaves the way it does are a shrinking group, and some have already left.

So the real specification of a legacy system is the running code, and reading it is brutal work. A system of millions of lines, written in a language whose experts are retiring, holds its most important behavior in the places nobody thinks to look: the rebate hard-coded for one large customer, the validation that exists because of an incident in 2014, the batch sequence that must run in a specific order for reasons long forgotten. Manual analysis of a system that size is measured in months, and it is never truly complete — you stop when you run out of time, not when you run out of system.

What AI changes: comprehension at scale

This is the work AI compresses dramatically, because reading and pattern-finding across enormous codebases is precisely what it is good at. AI-accelerated discovery reads the codebase, data, docs, and APIs end to end; maps the dependencies; and surfaces the domain rules nobody documented — not a sample, the whole thing. It does the exhaustive reading that humans run out of time and people to finish.

The effect on the timeline is real and bounded: AI-accelerated discovery is about 10× faster than manual review — a typical 12-week analysis compresses to roughly two weeks. Read that precisely. It is an analysis-time claim, scoped to comprehension; it is not a general “10× productivity” multiple across the program, and anyone who restates it that way is overselling it. The honest version is narrow, which is exactly why it holds up: faster reading of a specific, definable activity.

What makes the speedup matter is not the speed itself but what it enables. A faithful map of what the system actually does is the input to every later decision — scope, architecture, the slice plan, the validation targets. Get the reading right and the program rests on solid ground. Get it wrong and every downstream choice inherits the error, which is why the comprehension step is worth doing thoroughly even though AI makes it fast.

The output: living specs, not a dead document

A pile of generated documentation that nobody maintains is worth very little — it is stale the week after it is written, and then it is just another misleading artifact. So the output of discovery is not a one-time report. It is a set of living specs: documentation derived from the actual codebase that the team owns and keeps current as the system changes.

Living specs do three jobs at once. They are the source of truth for planning — each slice is scoped against what the system genuinely does, not what someone remembers. They are the validation target — the recovered behavior is what each modernized slice is later proven against. And they are the handover — when the modern system ships, the people who maintain it inherit documentation that is true, instead of the oral tradition that made the legacy system fragile in the first place. Knowledge that lives only in retiring heads is a liability; knowledge captured as a living spec is an asset the business keeps.

Why a human reviews the map

Here is the discipline that separates this from “let the AI document it and move on.” AI-accelerated comprehension is powerful but not omniscient. It can misread intent — flagging a quirk as a rule, or a rule as a quirk. It can miss context that lives entirely outside the code: a regulatory requirement, a contractual obligation, a decision made in a meeting that the source only half-reflects. And it can present a confident, well-organized map with quiet gaps that look exactly like the parts it got right.

So the map AI produces is evidence to review, not gospel to trust. Engineers confirm the findings, label which recovered behaviors are intentional, and decide what each one means for the modernization. This is the first place the human-in-the-loop model shows up concretely, and it sets the pattern for the whole program: AI reads exhaustively and fast; the human judges what the reading means. The reading is not the decision.

Where reverse engineering fits in the program

Step	What it produces	What depends on it
AI-accelerated discovery	A map of behavior, dependencies, and undocumented rules	Everything downstream
Human review	Confirmed, labeled living specs	A plan grounded in reality
Slice planning	Scope and sequence per slice	A safe order of work
Parity validation	Proof each slice matches the legacy	A cutover you can defend

The chain only holds if the first link is sound. That is why discovery comes first in the methodology and why ModernLift runs it as a fixed-price Discovery phase that produces a blueprint and roadmap before any code is touched — the Discovery deliverables are the architecture blueprint, the domain model, the migration roadmap, and the test and traceability framework that the rest of the program is built on.

Two limits worth stating plainly

First, AI-recovered documentation is a hypothesis about the system, not a certified truth — it is excellent at finding what the code does and silent about what the code should do, and only validation against the running system later turns the hypothesis into proof. Treating the generated map as final is the same mistake as trusting generated code without a parity gate. Second, comprehension is necessary but not sufficient: knowing exactly what a system does does not tell you what to keep, what to fix, or how to shape the replacement. Discovery makes those decisions informed; it does not make them for you. A perfect map of the wrong territory is still the wrong territory.

Where this leads

With the system understood and the behavior captured, the work turns from reading to writing — from “what does this do” to “how do we rebuild it.” That step has its own contested question: should code be translated by deterministic, rule-based tools or by language models? Part 4, AI Code Translation: Deterministic vs LLM, takes apart the two approaches, why each fails alone, and why the spec recovered here is what makes either one usable.