codebase-onboarding

# Codebase and Field Onboarding Build a verified map of an unfamiliar codebase, project, or research area before planning or editing anything. The output is a reconnaissance report that separates verified facts from assumptions, ending in a one-paragraph diagnosis. ## The bootstrap sequence (run in this order) 1. **Date and inventory.** Run `date`. List the tree (source dirs, configs, docs). Note the largest files with line counts; they are usually where the complexity lives. 2. **Intent docs before code.** Read `AGENTS.md`/`CLAUDE.md`, `README`, `.context/` (plan.md, research.md, decisions/), design docs. These say what the project is SUPPOSED to be. 3. **Code next.** Read entry points, the main loop or route table, and the one or two central types. Do not read everything; read what the intent docs point at. 4. **History.** `git log --oneline -20`, open issues and PRs (`gh issue list`, `gh pr list`). What was recently worked on, what is planned, what is stuck. 5. **What is ACTUALLY running.** Processes, containers (`docker ps -a`), data directories on disk, deployed endpoints, cron entries. This step distinguishes "designed" from "operated": if the design exists in code and issues but there is no runtime data on disk, the true next step is "turn it on and calibrate", not "design more". 6. **Verify the specific claim.** Whatever question triggered this onboarding ("does compaction work?", "is the migration done?"): grep the source and check live state for it directly. Absence of a script is not absence of work; completed one-off scripts get deleted. 7. **Probe third-party surfaces.** Before planning against any SDK or API, run one cheap introspection command against the INSTALLED version (import it, list the dataclass fields, hit the version endpoint). Treat your trained-in knowledge of library internals as a hypothesis. 8. **Diagnose in one paragraph.** State plainly what exists, what runs, what is broken or missing, and what that implies, before proposing any action. ## Delegating exploration (2+ independent areas) Split "where is X" (mechanical mapping, delegate it) from "what does X actually say" (judgment docs such as ADRs and strategy docs; read those yourself). When the area is larger than one context can hold: Use the worker/intermediate tier for bounded scouts (Codex Luna/Terra or Claude Sonnet), but keep diagnosis, keystone verification, and synthesis on the lead tier (Codex Sol or Claude Fable/Opus). Close/remove each one-off scout after its report is incorporated. See `agent-fanout` for escalation rules. - Partition by architectural domain (backend / CLI / web / data / infra) with disjoint file ownership, one read-only explorer per domain, all spawned in parallel. Agent count = number of genuinely independent domains, within the fan-out cap (see the agent-fanout skill). - For a planned file decomposition: one explorer maps the target file's internal structure (symbol inventory with line ranges, module-level mutable state), a second maps external dependents (importers, test doubles, dynamic imports), and a third reads the merged precedent of a prior similar change, to mirror it. - Every explorer prompt: numbered falsifiable questions naming the suspected files/symbols, an explicit READ-ONLY instruction, and the output contract "file:line references for load-bearing facts; conclusion-oriented; no file dumps". Template in `references/exploration-prompts.md`. - **Re-verify the keystone fact yourself.** Before any explorer conclusion becomes a headline claim or a plan premise, spot-check the single most load-bearing fact directly (one grep or file read). Explorer reports are hypotheses with citations, not ground truth. ## Field / literature onboarding (research areas) 1. Run broad searches yourself first and save the raw corpus (queries and results) to files; then delegate one summarizer per topic family with a hard reading list, exact deliverable path, and a bounded return summary. 2. Prefer primary sources (specs, papers, official policy pages); use general web search only as a fallback when a primary source is unreachable. 3. Record per-family findings in `research/<family>.md`, synthesize into one survey doc, and record the resulting decision as an Architecture Decision Record (ADR) with a dated log line in `.context/research.md` ("Problem, To investigate, Decision (date), Rationale"). 4. If the project's own docs name a preferred tool or skill for surveys and you choose differently, say so in one sentence at the point of choice. ## Output contract: the onboarding report ```markdown ## Diagnosis [One blunt paragraph: what exists, what runs, what is missing/broken, what it implies.] ## Architecture map [Components, how they connect, entry points; file:line for each claim.] ## Conventions observed [Naming, testing, error handling, commit style; where the house rules live.] ## What actually runs [Processes/containers/data found, or "nothing is operating" if so.] ## Verified facts vs assumptions - Verified: [fact (file:line or command output)] - Assumed (spot-check before relying): [assumption] ## Recommended next step [One step, justified by the diagnosis.] ``` ## Rules - No edits during onboarding. This skill is read-only; if you find a bug, record it in the report or file an issue. - On shared or remote machines, reconnaissance is read-only commands only (hostname, resource listings); never change drivers, caches, or system state on a box other people use, even to fix an obvious problem; report it instead. - Do not stall on ambiguous or typo-heavy briefs: state your reading of the request in one sentence with an opt-out ("proceeding on that basis; correct me if you meant otherwise") and start the bootstrap sequence.