Understanding undocumented legacy code: the one-hour spoken walkthrough

Every codebase has the module everybody knows by reputation and nobody has read: the thousand-line file with the name that promises something modest, the one that printed a stack trace during the last three outages, and the one whose comments are from two feature teams ago. Tickets arrive with the same warning attached: careful around that module. The warning is a symptom, not a diagnosis, and it is the reason understanding undocumented legacy code feels like archaeology; somebody once stepped on it, nobody wrote down what actually happened, and the memory of that injury has become the module's only documentation. Inheriting it feels like being handed a locked room, and the safe play is to make the smallest possible change in the farthest corner and hope the ticket accepts it.

The radical observation is that the risk is not the module, it is the summary. Nobody can say what the module does in a sentence, what it assumes, and which of its paths are actually dead, so every change has to be made blind, and blindness is what makes people tiptoe. A summary is not a luxury; it is the load-bearing wall of the whole development experience. The entire trick of inheriting such a module well is to rebuild that summary quickly, and the quickest way to rebuild a summary that nobody typed is to generate one by walking the code out loud. The walkthrough is not archaeology; it is narration followed by verification.

The tiptoeing also has a social cost that goes unmentioned: the module's caretaker, usually the one who wrote it, gets asked the same four questions forever, and each question is a context switch that could have been answered by a sentence on the record. When you take the time to read the module properly, you are not only unblocking yourself, you are unblocking every future ticket about the same file and giving the caretaker their hours back. That is why the walkthrough is worth an hour even when your ticket is a two-line fix: the two-line fix is the second ticket of ten that will land in the same file.

Choose the hour deliberately and guard it. Put the file open, the log viewer, and the test suite in front of you, and tell the team you are reading the module, which is permission for them to stop sending you around it. In practice the biggest blocker is never the file's complexity, which is usually ordinary; it is the social habit of fearing it. Complexity gets named, fear does not, and the walkthrough is the ceremony that converts the fear into a name. After the hour you will know whether the module deserves its reputation or merely got lucky with a famous incident, and the difference determines how you work its next ticket.

Open the module and begin at its entry point, and walk it aloud in the order the code executes rather than the order the file arranges itself. Say what you see, plainly, the way you would narrate a map to a driver: this function receives the payload, it checks the tenant, and then it branches into the offline path, where the cache is read. The narration does not need to be clever; it needs to be continuous, because the gaps in your narration are the gaps in your understanding, and hearing yourself pause at a line is the signal that there is something there you do not yet get. The assistant can be your walking partner, and it is a good one, because the agent reads ahead, answers the mid-walk question, and takes the notes while you keep talking.

Walk faster than feels comfortable, since the purpose of the first pass is coverage, not comprehension; save the deep dive for the three spots your own voice marked. The first pass should take about twenty minutes for a thousand-line file, and at the end you should be able to say the module's story in three sentences: what enters, what happens, what comes out. If you cannot, the assistant can summarize the walk from your own notes and the code, and reading its summary aloud is itself a second pass, since the mismatch between the summary and the screen shows you exactly where your story is still a guess. Testing the story is the discipline that separates a real understanding from a confident impression.

During the walk, collect the vocabulary of the module: the names of its concepts, its case conventions, its error language. Write each new word in a line as you meet it, since the vocabulary is the cheapest bridge into the module. In six months a new inheritor can read a glossary of fifteen words and immediately read the file as a normal piece of code rather than as a foreign document. The vocabulary list is also what you will use to search the module quickly later: when the outage again lists a cache miss, you know the word to grep for and the walk gives you the neighborhood of the file that uses it.

Do not let the walk drift into fixing anything. The temptation, once you see the dead function or the duplicated block, is to make the tiny improvement that feels therapeutic, and that is exactly how a walkthrough becomes a side quest and an unreviewed change. Say the rule aloud: today I read, I do not fix; the fixes get written down and shipped tomorrow with a plan. The rule keeps the hour honest, and the written-down list becomes the most valuable artifact of the session: a menu of small, understood improvements that future tickets can use, chosen by the only person in the company who has actually read the whole file that week.

A module that causes recurring outages has wrinkles, not mysteries, and typically exactly three of them: the shared mutable state that some request thread mutates, the time-sensitive path that depends on a cache or a clock, and the validation that silently tolerates bad input instead of rejecting it. The walkthrough should surface these by name, and the naming is what makes them addressable. Say them the moment you recognize them: this static counter is the first wrinkle, because two workers update it without a lock; the second is the timeout that retries forever under slow database conditions; the third is the missing field check that lets an empty record through to the formatter.

Each named wrinkle gets a one-line explanation of how it contributed to the outages you have been inheriting. The static counter explains the intermittent spikes, the retry loop explains the hour-long hangs, and the missing check explains the corruption reports. When the cause of an outage stands in the code with a name, the outage loses its mystique, and losing the mystique is exactly the point: a named wrinkle is a known trade-off, while an unnamed one is a rolling horror story that every new engineer re-experiences. The team should keep the names in a shared note so that the next incident can be discussed as a reference rather than rediscovered as a legend.

Rank the wrinkles by how much of the outage history each one accounts for, and say the ranking with your evidence: the retry loop explains two of the last three major incidents, the static counter the spikes, the missing check the corruption, so the retry is first. Ranking creates a roadmap where the first fix addresses the pain the team knows best, and a roadmap is what the ticket becomes, rather than a vague cleanup request that nobody wants to estimate. Ask the assistant to check the incident log against your ranking and to flag any wrinkle that explains more incidents than your walkthrough suggested, since the log check is the honest validation of the walk.

Resist the urge to fix the wrinkles immediately, no matter how small they look, because the deepest irony of legacy modules is that their fixes are only safe once their other two wrinkles are understood. The static counter fix, done wrong, makes the retry path worse; the retry fix, done wrong, makes the corruption path visible. Say the interdependency out loud so the team hears the sequencing rationale: fix the retry first, then the counter, then the validation, and between each one, run the full battery. A legacy module is a knot, and the order you untie it in matters more than the force you apply, which is why the naming hour earns its keep long before the first fix ships.

The walkthrough ends with a decision about scope, and the correct scope for a first visit is one path, the risky one, not the whole module. Say the path out loud: the offline branch, the one that reads the cache and retries, is the one that caused the outages, and that is the one we make smaller and safer; the rest of the module stays frozen. Freezing the rest is a spoken commitment, because the moment the refactor starts, the file's other paths will tempt you with their ugliness. A frozen module that gains a well-understood core is better than a half-rewritten module that nobody dares touch again, and the discipline of one path keeps the change reviewable on a Friday afternoon.

Behavior-identical is the standard, and it is stricter than it sounds. Before any edit, run the module's existing tests plus the reproduction of the outage, and record the baseline output, then ask the assistant to write a golden test for the risky path: the same input triggers the same observable behavior, whatever that behavior is, including the correct and the incorrect. A golden test that captures current behavior is the only honest ground truth for legacy work, since any improvement claim you make is a claim you should have to defend. Dictate the expectation in one sentence: the new version must produce the same three outcomes for the same three inputs, even though we know one of the outcomes is wrong.

Make the changes in the smallest steps that stay green, and narrate the intent of each step before the assistant performs it: step one, replace the bare retry loop with a bounded one and keep the same sleep schedule; step two, move the cache read behind a helper so the test can see when it is called; step three, add the explicit reject for the empty record but keep the exact same error code. Bounded, observable, and backward-compatible are the three adjectives of a legacy-safe step, and saying them on each step is the habit that keeps the rewrite honest. Run the golden test and the full suite after each step, and the voice you hear saying green, green, green is the sound of the module becoming yours.

Keep the diff small enough that the reviewer can actually review it, which is the discipline that protects you more than it protects the code. A two-hundred-line diff in a legacy module is untrustable by anyone, including you, while a set of four forty-line diffs, each with a spoken rationale in the commit description, is reviewable by a teammate on a second pair of eyes. Commit after each step, not all at once, and let each commit carry its one-sentence purpose. When the team sees a series of small, justified commits landing on the untouchable module, something changes in the room: the module stops being a haunted house and becomes just a file, and the next ticket about it arrives without the warning attached.

The walkthrough was an hour of careful work, and it becomes valuable the moment it is shared, so put the notes in the module itself before anywhere else: a short glossary at the top of the file, a one-paragraph explanation of what the module does and whom it serves, and the three wrinkles as a named list with their ranked explanations. A reader who opens the file for the first time should meet the summary before the code, and the summary written by an inheritor, not an author, is the kind that actually helps, because an inheritor writes for the next inheritor in the voice both of them need. Tell the assistant to place the notes as a comment block, and keep them short enough to read in ninety seconds.

The second copy of the notes belongs where the fear lives, which is the documentation index and the team wiki: a link to the module's glossary, the three wrinkles, and the one-line rule the team should know, such as never call this retry path from a controller. Adopt the rule into the walkthrough notes for the team, because unwritten rules are the tiptoe origin: everyone knew the module was risky, nobody knew why, and a risky thing with a one-line reason becomes a managed thing. Also record the decisions locked during the rewrite: why the retry is bounded now, why the golden test asserts the old error code, since these are the answers to the questions the next inheritor will ask in week three.

The third copy is spoken and cheap: a two-minute voice walkthrough, recorded while it is fresh, in which you say the story, the wrinkles, and the one fix that landed. The recording is the fastest transfer of understanding that exists, and it travels where documents do not: in the on-call handover, in the onboarding chat, in the incident postmortem. Team members replay it while they read the file, and the combination is effectively a tutorial that costs you nothing to maintain. When the trend arrives, these recordings are the onboarding asset, and the next inheritor can get to productive work without asking you to re-live every legacy trauma of the module by memory.

Then set a soft date for the next walk: ninety days from today, or after the next incident on the module, whichever comes first, check the glossary against the actual code and see whether the wrinkles list is still the truth. The notes are alive, and a deadline keeps them that way, since a glossary that drifts from the code is worse than no glossary, because it gives the reader false trust. Answering the question, so what did your walkthrough notes actually save, is the last step: a measured answer in a team note, such as the last two tickets on the module needed zero interruption, is the kind of evidence that makes the next engineer, and the next team, do the walk on their own.