explore-codebase

# Explore Codebase You are building a **mental map** of an unfamiliar or large codebase region. The goal is structural comprehension — understanding what the code does, how it's organized, and what the key entry points and invariants are — without loading everything into your main context window. This skill exists because codebases are too large to read in one prompt. The pattern (Recursive Language Model — see the RLM substrate section in CLAUDE.md) is: keep your root context small, dispatch sub-agents to read individual files or modules, and have each sub-agent return a structured summary. Synthesize the summaries into a coherent map. This skill covers **any** codebase the agent encounters — forks, dependencies, unfamiliar regions, user projects. For analyzing yoyo's own source to find bugs and gaps, use `self-assess` instead. ## When to use Trigger this skill when ANY of these hold: - A planned task touches **>5 files** you haven't recently worked on - A community issue references a feature or module you don't have a mental map for - You're investigating a bug whose surface spans **multiple modules** you haven't read recently - A new dependency is being introduced and you want to know its public API + key invariants before integrating - A user explicitly asks you to explore, understand, or map a codebase - `/add` brought in a large project and you need structural context before acting - You're working in a fork and need to understand what the fork changed relative to upstream ## When NOT to use - **Small known regions.** A single file ≤300 lines, or a function you wrote yesterday — just read it directly. Sub-agent overhead exceeds the savings. - **Precise edits across files.** Refactoring needs mutual context (seeing all pieces at once), not summaries. Summaries lose the fidelity you need for surgical edits. - **Sequential workflows with strong mutual context.** When each step depends on the full output of the previous step, fan-out doesn't help — you need serial reading. - **The region is already known.** If you or the user can name the exact module and its API from memory, direct read is faster. Don't explore what you already understand. - **You're inside a sub-agent at depth 3.** Stop. Return what you have. Do not dispatch further. ## Procedure ### 1. Identify the region Define the exploration scope — be specific: - A directory: `src/format/` - A file glob: `src/agent_builder.rs src/main.rs src/tools.rs` - A dependency: `~/.cargo/registry/src/*/yoagent-*/src/` - A commit range: `git diff main..feature-branch --name-only` If the scope is vague ("understand this project"), start with orientation (Step 2). If the scope is precise (a named set of files), skip to Step 3. ### 2. Orient — build a rough map Before dispatching sub-agents, gather cheap structural signals directly: ```bash # Project structure find <root> -type f -name '*.rs' | head -50 # or use /map if available in the REPL # README / docs cat <root>/README.md 2>/dev/null | head -100 # File sizes (to plan dispatch) wc -l <root>/src/*.rs | sort -rn | head -20 # Recent activity git log --oneline -20 -- <root>/src/ ``` From this, build a **file inventory** with rough sizes. Files >300 lines are candidates for sub-agent exploration. Files ≤300 lines can be read directly if needed later. ### 3. Decide: direct read or sub-agent? For each file in the region: - **≤5KB (roughly ≤150 lines)**: Read directly with `read_file` or `bash`. No sub-agent needed. - **>5KB**: Dispatch a sub-agent (Step 4). Don't load large files into your main context. If the total region is small enough to read directly (≤5 files, all ≤5KB), skip sub-agents entirely — just read and synthesize in your main context. ### 4. Dispatch per-file sub-agents Store each file's content in shared state, then dispatch a sub-agent to summarize it. **One file per sub-agent** — files are the natural unit of structure in code. #### 4a. Store the artifact ``` shared_state set key="explore.<region>.<filename>" value="<file contents>" ``` Namespace convention: `explore.<region>.<filename>` (e.g., `explore.format.markdown`, `explore.yoagent.agent`). If a single file exceeds 30KB (~120,000 bytes), chunk it before storing: - Split into chunks of ~80KB with 8KB overlap between consecutive chunks - Store as `explore.<region>.<filename>.chunk-1`, `.chunk-2`, etc. - Dispatch one sub-agent per chunk (same as analyze-trajectory's Section 3.5) #### 4b. Dispatch the sub-agent ``` sub_agent: You are exploring a source file to build a structural summary. The file is stored in shared state under key "explore.<region>.<filename>". Read it with: shared_state get key="explore.<region>.<filename>" Describe this file's structure in a JSON response. Reply with ONLY a JSON object (no markdown fences, no prose): { "file": "<filename>", "purpose": "1 sentence: what this file does", "public_api": ["list of exported functions/structs/traits with 1-line descriptions"], "key_invariants": ["non-obvious behaviors, constraints, or assumptions"], "dependencies": ["other modules/crates this file depends on"], "dependents": ["who calls into this file, if visible from imports/use statements"], "complexity": "low|medium|high", "deeper_question": "a follow-up question if something is unclear, or null" } ``` **Skills do not chain.** Sub-agents don't load this skill or any other; include the full question and shared-state key reference directly in the sub-agent's prompt. #### 4c. Handle sub-agent responses Parse each sub-agent's response as JSON: 1. **Valid JSON with all fields**: Store the summary in shared state under `explore.<region>.<filename>.summary` for the synthesis step. 2. **Malformed JSON but readable text**: Extract what you can. Construct a partial summary: `{"file": "<filename>", "purpose": "<first 200 chars of response>", "public_api": [], "key_invariants": [], "dependencies": [], "dependents": [], "complexity": "unknown", "deeper_question": null}`. 3. **Empty or errored**: Fall back to direct read of the file's first and last 50 lines. Produce a low-confidence summary manually. ### 5. Recurse on deeper questions If a sub-agent returns a non-null `deeper_question` and `complexity` is `"high"`: 1. Dispatch another sub-agent with the narrower question, referencing the same shared-state key. 2. Merge the answer into the existing summary. **Hard cap: recursion depth = 3.** That's: initial dispatch → 1st recursion → 2nd recursion. After depth 3, accept whatever you have. If you find yourself wanting depth 4, your initial scope was probably too broad — narrow the region and retry. ### 6. Synthesize into a mental map After all per-file summaries are collected, dispatch a **synthesis sub-agent** (or do this in your main context if the total summary data is small enough, ≤5KB): ``` sub_agent: You are synthesizing per-file summaries into a structural map of a codebase region. The following shared-state keys contain per-file summaries: - explore.<region>.<file1>.summary - explore.<region>.<file2>.summary ... Read each summary, then produce a structural map as a JSON object: { "region": "<region name>", "overview": "2-3 sentences: what this region does as a whole", "module_graph": ["<file-A> -> <file-B>: <relationship>", ...], "entry_points": ["the key functions/structs a caller would use"], "invariants": ["cross-file constraints or assumptions"], "risk_areas": ["files or interactions that look fragile or complex"], "open_questions": ["things the summaries couldn't resolve"] } ``` ### 7. Use the map The mental map is your working context for the rest of the session. Reference it when: - Planning which files to modify for a task - Estimating the blast radius of a change - Deciding whether a refactor is safe - Explaining code structure to a user or in a journal entry Store the final map in shared state under `explore.<region>.map` so sub-agents in later steps can reference it without re-exploring. ## Pitfalls - **Don't explore what you already know.** If you wrote the code recently or have it in active memory, skip this skill. It's for building *new* understanding, not confirming existing knowledge. - **Don't ask sub-agents to make decisions.** They summarize structure; you decide what to do with it. Sub-agents that plan or recommend tend to drift. - **Don't dump multiple files to one sub-agent.** One file per dispatch keeps the JSON output reliable and the summary focused. The synthesis step is where cross-file reasoning happens. - **Don't forget the recursion cap.** 3 is the hard limit. If your region needs depth 4, the region is too broad — split it. - **Don't explore before acting on small tasks.** If the task is "fix this one function," reading that function directly is faster than exploring the whole module. Match the tool to the task size. - **Don't re-explore within the same session.** If you've already explored a region, the summaries are in shared state. Read them with `shared_state get` instead of re-dispatching sub-agents. - **Per-file, not per-byte.** Unlike analyze-trajectory (which chunks CI logs by byte offset), this skill fans out by file. Files are the natural structural unit in codebases. Only chunk within a file if it exceeds 30KB. ## Verification An exploration is "good enough" when ALL of: - The map names **concrete files and functions** (not "some module that handles X") - Each file in the region has a summary (even if low-confidence for some) - The module graph shows **how files relate** (who calls whom, who depends on whom) - Entry points are identified — a caller knows where to start - The total exploration used **≤ N+2 sub-agent dispatches** where N is the number of files explored (N per-file + 1 synthesis + 1 possible recursion) - The work stayed within the depth-3 recursion cap If the map fails any of these, narrow the region and re-explore the gap, or accept the partial result and document open questions. ## What this skill deliberately does NOT do - **Does not modify code.** Exploration produces understanding, not changes. The actual edits are a separate task. - **Does not find bugs.** That's `self-assess`. This skill builds the map; self-assess uses the map to find problems. - **Does not auto-create documentation.** If the map is worth preserving as docs, that's a separate decision outside this skill's scope. - **Does not write to the audit-log branch.** The exploration results live in shared state for the current session only.