The Legacy Trilogy — Understand, Document, Migrate

Legacy modernization is the work everyone needs and nobody wants: understanding a codebase no living person fully knows, documenting it, migrating it without breaking it. Three skills — code-documenter 9.3, legacy-modernizer 9.1, spec-miner 9.0 — turn out to be a matched set. Read them in order and they're a theory of how old software should be approached.

Every engineering org has the same graveyard: the system that runs the business, has no documentation, and is understood by exactly one person who is trying to leave. The standard answer is either heroic (a rewrite, which fails) or fatalistic (never touch it, which compounds). Three skills in our directory quietly assemble a third answer, and their order of operations is the whole thing.

The trilogy, in the order it must run

First, recover the spec. spec-miner — 9.0: reverse-engineer the specification the code actually implements — data models, behavior contracts, decision rules, the requirements that the original code silently decided. The premise of the skill is that legacy code is not merely unread; it's the only surviving record of what someone wanted, and it must be treated as an archaeological artifact, not an inconvenience.

Second, write it down. code-documenter — 9.3, the highest score of the three and among the best in the category: turn understanding into permanent documentation — architecture, interfaces, the "why" behind each design choice. This is where the recovered spec stops living in one engineer's head and starts living in the repo. The skill earns its 9.3 by making documentation a structured output with a definition of done, rather than the "I should really document this" that never happens.

Third, migrate — incrementally. legacy-modernizer — 9.1: a modernization strategy, and the strategy is strangler-pattern-style incremental migration: carve out one seam, replace one subsystem, keep the old one running alongside until the new one has earned the traffic. Never the big rewrite. Never "we'll port it all next quarter."

Why the order is load-bearing

Run them out of sequence and each one fails. Migrate first (legacy-modernizer with no spec) and you're rewriting behavior nobody understands — the classic failed rewrite, rediscovered. Document first without spec-miner and the docs merely describe the code at surface level, recording the confusion instead of dissolving it. Mine the spec and stop, and you've got an artifact no one acts on.

The trilogy's implicit claim — and we agree with it — is that legacy failure is almost never a code problem. It's a knowledge-capture problem: the code is intact; what died is the reasoning. So the workflow puts knowledge recovery first (9.0), knowledge externalization second (9.3 — the most valuable step, scored accordingly), and code change last (9.1). Fix the epistemology before the syntax.

Why agents are structurally good at this

There's a reason all three skills score 9.0-plus, and it isn't that the tasks are easy — they're the tasks human teams chronically defer, because reading old code produces no urgency and no demo. Human organizations can't staff it: the senior engineers who could do it are busy shipping features, so the knowledge decays one departure at a time.

Agents have no urgency economy. Reading a 40-year-old payroll module line by line and writing down what each branch implies costs the same attention unit as writing a flashy new feature — there is no internal bias toward the exciting task. That's not intelligence; it's indifference to boredom, and legacy work is the exact domain where boredom is the bottleneck. spec-miner's 9.0 is the quiet evidence: it packages the patience.

legacy-modernizer at 9.1 earns its keep on the other half — the discipline humans lose under pressure to show progress. Incremental migration means months of running both systems before the old one dies, and the skill exists precisely to hold that line.

Old code doesn't need a rewrite and doesn't need a hero. It needs a spec recovered, a document written, and a migration patient enough to survive contact with production. Three skills, in that order — and the trilogy closes with the system still running, which is the only ending legacy work ever gets.