Repo Onboarding Map

The README describes the project someone intended to build. The code is what got built, and the gap between them is where every new contributor loses their first week. This skill closes that gap by reading the code and the history rather than the documentation, and produces two artifacts: a map for a human, and a context file for the next agent session.

1. Establish the perimeter

Before reading any application code:

• Entry points. main, index, cmd/, route files, queue consumers, cron entries, CLI commands. Grep the process manager or Procfile, and read the scripts block — it tells you how the team actually runs this thing.
• The dependency list, read for signal rather than completeness. The web framework, the ORM, the validation library and the test runner tell you most of the architecture before you open a file.
• The local loop: how to install, run, test and reset. If you cannot get the test suite green locally, say so early and prominently — it is the single most important fact about a codebase and the one people are most reluctant to write down.
• Config and secrets: what environment variables exist, and which are required to boot.

2. Trace exactly one request end to end

Pick the most representative operation the system performs — usually the main create or the main read — and follow it all the way: entry, routing, auth, validation, business logic, persistence, response.

This is the highest-value hour of the whole exercise. One traced path teaches you the layering, the error convention, the transaction boundary and the naming style at once, and it teaches them as a connected whole rather than as isolated observations. Write the trace down as a numbered list of files and functions, in order.

3. Model the data

• Tables or collections, and the relationships that matter. Read the migrations directory in order — it is a changelog of what the team learned.
• Which tables are hot, which are append-only ledgers, which are caches that can be rebuilt.
• Where the schema is enforced: database constraints, ORM validation, application-level checks, or nowhere.

4. Find the hot spots from history

Opinion says the messy file is the problem; history says otherwise. Compute:

• Churn — commits touching each file over the last twelve months (git log --numstat).
• Churn × size or complexity — the standard hot-spot metric. High on both means a file that is hard to understand and changes constantly, which is where the cost is.
• Bug-fix concentration — files most frequent in commits whose message begins fix. This is the best cheap proxy for fragility in the whole repo.
• Bus factor — git shortlog -sn -- per directory. A directory with one author who left is a risk worth naming.

5. Infer the unwritten conventions

Read twenty recent merged pull requests or a hundred commits and answer, from evidence:

• How are things named — files, tests, branches, commits?
• Do tests accompany changes, and what kind?
• How are errors handled and logged, in practice rather than in the style guide?
• What gets reviewed hard and what sails through?
• What did the team try and abandon? Reverted commits and closed-unmerged pull requests are the only record of this, and it is the knowledge that takes newcomers longest to acquire.

6. Write the two documents

docs/repo-map.md — the perimeter, the traced request, the data model, the ranked hot spots with their numbers, the inferred conventions, and a short "if you are about to change X, read Y first".

A starter CLAUDE.md or AGENTS.md — only the facts an agent needs on every turn: the run and test commands, the layout rule, the conventions, the genuine landmines. Keep it short. Everything situational belongs in the map or in a skill, not in a file re-read on every message.

Judgement calls

• Depth over breadth. One request traced completely beats twelve files skimmed. Resist the urge to summarise every directory.
• Report the code, not the aspiration. Where the README and the code disagree, say so plainly and name both. That contradiction is the most useful thing a newcomer can be told.
• Do not propose refactors. This is a map, not an audit. Note what is fragile and stop there.

Verification gate

• The install, run and test commands were executed, not copied out of the README. Report which ones actually worked.
• The traced request names real files and functions, in order, and you followed it rather than inferring it from the structure.
• Hot-spot figures came from git log, with the window stated.
• Every claimed convention has an example commit or file behind it.
• The starter context file is under roughly 60 lines.
• Paste the command output for the local loop rather than describing it.