A First-Week Guide to Reviewing on an Unfamiliar Repo
Week one on a codebase nobody on the team has touched in years has a particular texture. The tests pass locally but fail in CI. The README describes an architecture that no longer exists. Someone left a comment that reads "temporary fix" dated 2019. The instinct is to start reading files, top to bottom, and build a mental model before leaving any comments. That instinct wastes the first three days.
A reviewer's job on unfamiliar ground is smaller and stranger than the job on familiar ground. The familiar repo rewards deep context. The unfamiliar one rewards a narrow, deliberate kind of attention: finding the few places where a change will actually break something, and refusing to spend review energy on the rest. Week one is about calibrating that attention before it gets spent in the wrong places.
Read the change, then read the file it lands in, in that order
The pull request is the entry point, not the codebase. Opening the repository first and wandering through directory trees feels productive and teaches almost nothing. Start with the diff. Read every line of it with the assumption that it is correct, and note where that assumption feels thin.
Then open the surrounding file, but only the sections the diff touches plus the twenty or so lines above and below. The question is not "what does this file do?" The question is "what does this file assume about its callers, and does the diff violate any of those assumptions?" A function that quietly expects a non-null argument and gets null is a bug visible from the diff alone, no architectural knowledge required.
The wander comes later, and only when the diff points somewhere. A changed signature sends the reviewer to the call sites. A new import sends them to the module being imported. Curiosity is the reward for a specific question, not the method.
The comment that explains why is worth more than the code that shows what
Unfamiliar codebases are full of comments that describe the obvious. "Increment counter." "Return result." Those are noise. The comments that matter are the ones explaining a decision: why this retry count, why this header is set, why this branch exists at all. On day one, a reviewer should collect those comments like currency.
A comment reading "// workaround for the legacy auth service, remove after migration" tells a reviewer three things at once: there is a legacy system, it is being migrated, and this code is expected to die. That single line is worth more than an hour of reading the auth module. The same goes for issue links, TODO markers with names attached, and commit messages that argue with themselves.
When a diff touches code near one of those load-bearing comments, the review should slow down. Those are the places where a change looks small and is not.
Run the tests before trusting them
Green tests on an unfamiliar repo mean less than they appear to. The first task is to watch them run, read a few, and figure out what they actually assert. A test suite with ninety percent coverage can still be checking almost nothing if every assertion is a truthiness check on an object that is always constructed.
There is a cheap diagnostic. Pick the test closest to the diff, break the code deliberately in a scratch branch, and confirm the test goes red. If it stays green, the test is decoration. Knowing which tests are decoration is the single most useful piece of week-one knowledge a reviewer can acquire, because it determines which failures in CI are worth chasing.
This takes maybe twenty minutes. It prevents a week of trusting a suite that has never once caught a regression.
Ask the question that reveals the owner
Every old repo has an implicit owner, sometimes a person who left, sometimes a person who is still there and dreads the ping. Finding that person early is not political maneuvering. It is the fastest route to the context that is not written down anywhere.
The trick is to ask a question that only someone with history can answer. "Why is this module structured this way?" gets a shrug. "Was this ever intended to handle the batch case, or was it added later?" gets a story. The story contains the constraints, the deadlines, the abandoned plan, and the reason the current change is risky.
A reviewer who asks three of these in week one will know more about the repo than a reviewer who reads for a month.
The diff that touches a boundary is the diff that matters
Most of a codebase is uninteresting at review time. The interesting changes cluster at boundaries: where data enters from outside, where it leaves to a third party, where one module hands off to another, where a schema is defined. An unfamiliar reviewer should develop a quick reflex for spotting these and spend time there.
A change deep inside a pure function is usually safe. A change to a serialization format, a database column type, or a public API response shape is where the blast radius lives. The reviewer's job is to find the boundary the diff touches and ask what else is on the other side of it.
On a first week, a reviewer will not know all the boundaries. They will find them by following the imports and the call sites outward from the diff until the picture gets fuzzy, then stopping. The fuzziness is a signal: that is where the next question goes.
Leave a map for the next reviewer
By Thursday or Friday, the reviewer has accumulated something valuable: a rough, personal map of the repo. Where the tests lie. Which comments are load-bearing. Who to ask. Where the boundaries are. That map fades fast. Writing it down, in a PR comment, a team wiki, or a single paragraph in the review summary, is the highest-leverage thing a first-week reviewer can do.
The note does not need to be polished. "Touched the billing path, tests around it are thin, the retry logic in invoice.go has a comment claiming it is temporary from 2021, asked Priya about it" is a complete and useful artifact. It saves the next unfamiliar reviewer a day.
There is a second benefit. Writing the map forces the reviewer to notice the gaps in it. The blank spots in the note are the next week's reading list.
Approve less, ask more, and say which is which
The strongest habit a reviewer can build in week one is to separate approval from inquiry. On an unfamiliar repo, an unconditional approve is a guess. A conditional approve, "looks right to me assuming the batch path is unchanged, can someone confirm?", is honest and useful.
The same applies to comments. A reviewer who writes a dozen "nit:" comments on style in an unfamiliar repo is signaling effort while avoiding the real question. A reviewer who writes two comments, one on a boundary and one asking about an assumption, is doing more with less.
None of this requires deep knowledge. It requires the discipline to point the questions at the places where uncertainty is highest and to admit which answers are guesses.
A reviewer who leaves the repo faster is not a failure
There is a quiet expectation on some teams that a good reviewer becomes the resident expert. On an unfamiliar repo in week one, that expectation is wrong and slightly harmful. The goal is to review the diffs in front of the reviewer well, learn just enough to be useful, and hand off the context cleanly.
By the end of the first week, the reviewer should be able to name the two or three files that matter for the current work, the one person to ask, and the test that actually catches things. That is a complete week. The deeper reading can wait for week two, and it should, because the diffs in week two will be different and the map will have moved.
The image to hold onto is the reviewer leaving Friday with a single page of notes and a clear sense of which questions are still open. Not an expert. A person who knows where to look next.
