map-repolisted

# Map an Unfamiliar Codebase The output is for someone about to change this code for the first time. That person does not need a directory listing — they can run `ls`. They need to know where execution starts, which five files carry the weight, and what is going to surprise them. Everything written here must be **verifiable from the code**. A map that is confidently wrong is worse than no map, because it gets trusted. ## Step 0 — Survey the structure Run `repo-survey . --pretty` (bundled as a bare command by this plugin). It returns JSON: file count, languages by line count, manifests, lockfiles, CI configs, npm scripts, likely entry points, top-level directories, existing docs, and git facts including the **most-changed files over the last year**. That churn list matters more than the file count. The files that change every week are where the work actually is, and they are rarely the biggest ones. Then read what already exists before writing anything new: `README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`, `docs/`, any ADRs, and any existing `CLAUDE.md`. Two reasons — you should not contradict them, and where they are **out of date** compared to the code, that gap is one of the more valuable things you can report. ## Step 1 — Set the depth - `--depth quick`: structure, entry points, how to build and test. No subsystem agents. Minutes. - `--depth normal` (default): the above, plus the three to six main subsystems mapped, plus data flow and conventions. - `--depth deep`