What to read first in an area of the codebase you have never opened

You have ninety minutes and a ticket in a part of the system you have never opened. Read in this order: what the area is responsible for, the last decisions recorded against it, what it assumes about its neighbours, what it deliberately does not do, and only then the code.

The order is the whole trick. In a codebase agents write, there is no author to interrupt, so the reasoning has to come off a record rather than out of somebody's head — which is what Backthread keeps, per area, including the places where the record is blank.

Why the code comes last

Reading files first is the instinct, and it is the expensive way round. The code answers what happens, exhaustively and without prioritising anything. What you need in order to change it safely is why it is like this, and that information was never in the file. Open the code before you hold the reasoning and you will spend an hour reconstructing intent from control flow, which is slow, and which produces a plausible story that may be wrong.

This is a reading plan for one person, for one area, before one change. If you are bringing someone into the whole system rather than one corner of it, the two-week version is a different plan.

The ninety minutes

1. What the area is responsible for, and what it talks to. Ten minutes. Top level only, on a map of the system rather than a folder tree. Stop when you can name its three nearest neighbours and say which way each dependency runs. If you cannot draw that from memory afterwards, the rest will not stick.
2. The last twenty decisions recorded against this area, newest first. Twenty-five minutes. You are hunting for the two or three that could plausibly have gone the other way. Expect most entries to be empty: on our own repository, 1,613 of 4,302 decisions captured from agent sessions carry any deliberation at all, so 62 percent record no alternative and no trade-off. A blank is not a gap in the record. It means the change was cheap and reversible and nothing was weighed, which is worth knowing before you treat a line as load-bearing.
3. The trade-offs somebody accepted on purpose. Ten minutes. Distinct from the alternatives in step two. You are looking for the shape "we took X, knowing Y, because Z was out of scope". These are where a reasonable-looking change detonates, and they are almost never in a comment.
4. What this area assumes about its neighbours. Ten minutes. Ordering, idempotency, who owns the write, how stale a read may be. The assumption your change breaks is rarely written down in the area that breaks; it is written, if at all, in the area that depends on it.
5. What it deliberately does not handle. Five minutes. An absence is a decision, and an unrecorded absence is the most common way a newcomer widens a change without meaning to. If nothing is recorded, write your guess down now and put it in the pull request as a question.
6. The last incident or revert in this area. Ten minutes. Nothing conveys the real failure modes faster, and it gives everything above something to attach to.
7. The context file your agents will load for this work. Five minutes, read as a claim rather than as fact. Check any number in it that will shape your approach. Ours overstated a graph by more than an order of magnitude for weeks, and it mis-scoped real work before anyone thought to measure.
8. Now the code — only the files the decisions pointed at. Fifteen minutes. Two things to find: lines that exist because of something you read, and lines nobody can account for. Write the second list down. It is the most useful artefact of the whole exercise and the one you will want in review.

What to skip on the first pass

• The README, unless it carries a date you trust. It describes the system as understood on the day somebody sat down to write about it.
• The test suite in full. Read the names of the tests for your area, not the bodies. The names are a specification; the bodies are a second codebase.
• The dependency graph below the top level. At leaf resolution it is true and useless.
• The commit log by author. Under agents it tells you who ran the session, which is not the same as who holds the change.

The honest counterweight

A pre-read is not always better than reading the source, and we have lost that comparison ourselves: in one head-to-head we ran, a flagship coding agent reading the source outperformed our own prepared summary on depth. So be clear about which question you are asking. For what does this do, the source is authoritative and a summary is a lossy copy of it. For why is it like this, and what did somebody already decide not to do, the source cannot answer at any length, and the record is all there is.

How to tell ninety minutes was enough

Do not grade yourself on files read. Take the riskiest assumption you found in step four, go to whoever owns the neighbouring service, and state it back to them as a fact. If they agree, you have a working model. If they correct you, you have just bought the most valuable ninety seconds of the day, and the correction belongs in the record rather than in your head. Either way you now have the standing to ask the questions worth asking before a change merges.

The reason this order works at all is that somebody kept the reasoning. Where nothing was captured, steps two through five collapse into guesswork and you are back to reading control flow — which is the argument for keeping the record per area while the sessions that produced it are still open.

Connect one repo and the recorded reasoning for your busiest area is there to read the same day, blanks included; the trial runs fourteen days.