Codebase Onboarding: $ARGUMENTS

Principle

Understanding is built from behavior first, then structure, then history — run it before reading it, trace one real flow before mapping all of them, and let git log tell you what the files can't: where the work happens, who knows it, and what everyone is afraid to touch. The output is a written map, because comprehension that stays in one session's head is re-paid by every next session.

Read-only on app code. The only file you create is the orientation report.

Phase 0 — Context (works pre-bootstrap by design), and which mode you are in

Read README/CONTRIBUTING/docs index if present — as claims to verify, not facts: docs drift, code doesn't. Then pick the mode from whether the repo carries an active profile:

Cold mode — no .claude/PROJECT.md. The default, and what this skill was built for: run the full suite of phases below and build the map from zero. Don't stop for the missing profile.

Verification mode — an active PROJECT.md (plus CONTEXT.md, project rules, docs index). The repo is already profiled, so start from what exists, verify it against code, and report drift rather than rediscovering from scratch: read the profile's architecture/module map and commands first, then run the phases as checks on those claims — does the entry point still live where the map says, does the stated test command still pass, does the traced flow still go through the layers the profile names. Every phase still runs; what changes is that each one starts from a claim instead of a blank page, and disagreement between doc and code is itself a finding. Do not edit the profile — this skill is read-only; drift goes into the report so the user (or /bootstrap) folds it back.

Phase 1 — Surface scan (minutes)

• Manifest + lockfile → language, framework, the real dependency list (the framework in the lockfile beats the one in the README).
• CI config (.github/workflows, etc.) → how it's actually built/tested/deployed — CI is the only documentation forced to stay true.
• Top-level layout + entry points: main/app/cli/server/routes/jobs — what kinds of process exist (web, worker, cron, CLI)?
• Config surface: env keys, settings schemas, feature flags → the system's external knobs.

Phase 2 — Run it before reading it

If a run/test command is discoverable (CI, README, manifest scripts) and safe (no prod credentials, no external writes), run the test suite and/or start the app and hit one endpoint/command. Observed behavior anchors everything you read next — and a suite that doesn't pass on a clean checkout is finding #1. If nothing runs safely, say so in the report (it's an onboarding cost every newcomer will pay).

Phase 3 — Trace one real flow, end to end

Pick the most representative user-facing operation (from routes/CLI verbs) and trace it: entry → validation → domain logic → persistence → response/effects, citing path:line at each hop. One deep vertical teaches the architecture's dialect — layering, error style, DI wiring, naming — better than ten shallow horizontals. Where the repo is large, fan out Explore agents in parallel with distinct lenses (by-entry-points, by-tests, by-config), but trace the spine yourself: the spine is judgment, not sweep. Reconcile the trace against the Phase 2 run and mark each hop observed or inferred: reading misses the frames a framework injects — middleware, inherited callbacks, ORM hooks.

Read the tests as documentation: test names are the behavior vocabulary; fixtures show the domain objects' real shapes; what has no tests is the first danger-zone entry.

When re-reading a method stops paying, frame it: on paper, name each field it touches as a parameter, each mutation as a return value. A field overwritten before any read was never an input; a parameter you cannot name is a glossary candidate, not an "unclear" note.

Phase 4 — History archaeology (the part files can't tell you)

git log --format="%an" | sort | uniq -c | sort -rn | head   # who holds the knowledge (bus factor)
git log --since="6 months ago" --diff-filter=M --name-only --format= | sort | uniq -c | sort -rn | head -20   # churn hotspots
git log --format="%ad" --date=short -1 -- <dir>             # per-area last-touched

• Churn hotspots = where the business actually lives (and where bugs cluster — churn × complexity is the best bug predictor available without running anything). Drop generated files, lockfiles and locale dumps, then say WHY each survivor churns — feature work, repeated fixing, or a mass edit that orients nobody.
• Recent activity = the current front: what the team is building now.
• The untouched old code = either finished-and-stable or feared — git log --grep for revert/hotfix language around it tells you which.
• Skim merged PR/commit messages for the last month — vocabulary, active concerns, and how much process the team really uses.

Phase 5 — Seams, boundaries, weirdness

• Module map: the 5–10 real components and the dependency direction between them (delegate breadth to arch-tracer-style tracing where wiring is opaque).
• External surface: integrations, queues, storages — everything that leaves the process.
• Load-bearing weirdness list: everything that surprised you — the odd lock order, the duplicated constant, the hand-rolled thing a library usually does. Each entry is "surprising, reason unknown — check git log -L before touching" (core.md: surprise is evidence of a constraint you can't see; never normalize on first contact).

Phase 6 — The orientation report

Write to the plans location if PROJECT.md defines one, else offer ./ONBOARDING.md (confirm before creating). In verification mode the report's most valuable section is the drift list — that is what the user folds back into the profile and rules. Structure:

# <Repo> — orientation map (<date>)

## What this is · How to run/test (verified: <what you actually ran>)
## Architecture in 5 lines (+ the traced flow, path:line per hop)
## Drift vs docs (verification mode only — each claim in PROJECT.md / CONTEXT.md / project
##   rules that the code contradicts: the claim, the `path:line` that disproves it, and which
##   of the two is now right. Omit this section entirely in cold mode.)
## Hotspots (churn, filtered — with why each churns) · Current front · Bus factor
## Danger zones (untested / feared-old / weird-with-unknown-reason)
## External surface (integrations, storages, queues)
## Glossary candidates (domain terms → /domain-model)
## Open questions (what only the team can answer)
## Suggested next: /bootstrap (profile), /domain-model (glossary), /arch-health (debt scan)

Every claim observed (path:line, command output) or marked inferred. If /bootstrap runs next, this report is its input — offer to chain it.

Hard rules

• Run before you read; trace before you map; verify docs against code — README claims are tier-Guessed until observed.
• Read-only on app code; never "fix" anything mid-onboarding — weirdness goes on the list, not into a diff.
• Depth over coverage: one flow traced to the bottom beats every directory skimmed. Say what you did NOT explore — a map that hides its edges misleads (core.md).

See also

• /bootstrap — turn the map into PROJECT.md; /discover — one capability, known repo; /arch-health — debt scan once oriented; /domain-model — capture the glossary.