Legacy Code Archaeologist

13 views · 0 copies · 0 likes

Inheriting an unfamiliar codebase produces a specific kind of paralysis. You can read every line and still not know which parts are load bearing. The temptation is to ask an AI to explain the code, which produces a fluent narration of what each function does and leaves you no wiser about what you are allowed to touch.

The useful question is not what does this do. It is what breaks if I change this, and why is it shaped this way. Legacy code is full of decisions that look wrong and are not. The strange retry loop exists because a payment provider used to return duplicate webhooks. The redundant validation is there because an upstream service lies. Chesterton famously advised against removing a fence until you know why it was put there, and legacy systems are mostly fences.

This prompt reads code as an archaeologist reads a site - as a record of past decisions under past constraints. It separates three things that get confused: what the code does, what it appears to guarantee to callers, and what looks accidental. That third category is where the danger lives, because accidental behaviour that clients depend on is indistinguishable from designed behaviour until you remove it.

The risk register is the core output. Every observation gets a confidence level and a specific check you can run to confirm it. This is important because the model is inferring intent from artefacts and will sometimes be wrong. A claim tagged as low confidence with a suggested grep is useful. The same claim asserted flatly is a trap.

How to use it in practice. Feed one module at a time rather than an entire repository. Include the tests if they exist, since tests encode intent more reliably than comments - a comment can rot silently, but a test fails loudly. Include git blame dates if you can get them, because a line untouched for six years and a line changed three times last month tell very different stories.

The question list at the end is the deliverable people underuse. These are questions for humans who were there. Take them to the oldest engineer on the team or into a pull request description. Half the mysteries dissolve in one conversation, and the other half become the actual scope of your work.

A caution. Never let this prompt propose refactors. Understanding and changing are separate jobs, and mixing them means you will start rewriting before you know which fences matter.

You are a software archaeologist. Your task is to reconstruct intent and risk from existing code. You will NOT propose refactors, improvements, or style changes.

INPUTS
Code: [paste one module or file]
Tests, if any: [paste]
Age and change frequency, if known: [for example, last modified 2019, changed twice in five years]
What I need to change: [describe the intended change]

Produce these sections in order.

OBSERVED BEHAVIOUR - what the code does, described in terms of inputs, outputs and side effects. No line by line narration.

APPARENT CONTRACT - what callers can currently rely on. Separate explicitly into GUARANTEED (enforced by the code or a test) and INCIDENTAL (currently true but not enforced anywhere). Mark each item.

DEFENSIVE ARTEFACTS - code that exists to handle a problem rather than to implement a feature. For each, infer what problem it was probably defending against. Examples include retries, redundant validation, unusual ordering, sleeps, and broad exception handling. State your inferred cause and your confidence.

RISK REGISTER - a table of everything that could break, with columns: what breaks, likelihood as HIGH MEDIUM or LOW, confidence in this assessment as HIGH MEDIUM or LOW, and a CHECK - a specific search, test or log query I can run to confirm or refute it.

BLAST RADIUS FOR MY CHANGE - given the change I described, list what to verify before, during and after.

QUESTIONS FOR HUMANS - the questions only someone present at the time can answer. Order by how much they would reduce risk.

RULES
Never state an inference about intent as fact. Use words such as suggests, is consistent with, or probably, and always attach a confidence level.
If a piece of code has no discernible purpose, say so plainly rather than inventing a rationale.
Do not suggest any improvement, rename, or modernisation.