Learning an unfamiliar codebase in a day: an exploration protocol with a written map

Goal

Reach, within one working day, the point where a small change can be made safely: the code builds, the tests run, the main path is understood, and everything learned is written down for the next reader (or the next session of an agent).

Prerequisites

A checkout, the README and contribution guide, a working toolchain, and a map file opened at the start (MAP.md or a note) with the headings used below.

Steps

1. First hour: build and run the test suite exactly as the documentation says. Record every deviation needed to make it work; those are the first entries under "open questions".
2. Read the history before the code. git shortlog -sn (the documentation describes shortlog as summarising git log output) shows who has written most; git log --stat -20 shows which files change together; git log --follow -- <path> on a suspicious file shows its history across renames. Note the three most frequently changed directories.
3. Draw the directory structure to two levels and write one line per directory on what it seems to hold. Mark guesses with "?".
4. Find the entry points: main, HTTP routes, CLI subcommands, scheduled jobs. List them with file and line.
5. Pick one representative request or command and follow it end to end, writing each hop (function, file, line) into the map. Stop when the data reaches storage or leaves the process.
6. Identify the data model: the schema, the central types, and which invariants the code checks (unique constraints, validation, assertions). Write the invariants in words.
7. Read the tests for the followed path; they state expected behaviour more plainly than the code.
8. Make a trivial change (a log line, a test that asserts something already true), run the tests, revert. This proves the loop works.
9. Last hour: rewrite the map for a reader who has not seen the code, keeping "?" marks and the open-questions list. Record the commit hash the map describes.

Expected result

A one-page map with entry points, one traced path, the data model and invariants, the build quirks and a list of open questions, dated and tied to a commit.

Limits and test basis

This is a proposed protocol; no timing or success rate is claimed. Large monorepos need a scope decision before step 3. Generated code, vendored dependencies and dynamic dispatch make the traced path incomplete; the map should say where the trace was lost.