/sdlc:explore-codebase

Generated from solutions/ontological/skills/explore-codebase/SKILL.md.

Description

Systematic method for understanding an unfamiliar codebase: getting oriented in a new repo, locating where something is implemented, tracing how a feature or request flows end to end, and building an accurate mental model before answering questions or making changes. Use whenever you’re dropped into a repo or the user asks things like “how does X work here”, “where is Y handled”, “how is this project structured”, “help me understand this codebase”, “onboard me to this code”, “find where Z is implemented”, or “explore this repo and write up notes” — or before editing code you haven’t read yet. Can optionally save the resulting map as a markdown file or a linked Obsidian-style vault in a temp location.

Allowed tools

• Read
• Glob
• Grep
• Bash
• Agent
• Write

Source

Build an accurate, verifiable mental model of a codebase as fast as possible, spending the least context to get there.

The rule that governs everything

Context is your budget, and performance degrades as it fills. Never read the whole repo. Search first, read narrowly, confirm against the source — never describe behavior you haven’t actually seen in a file.

Work top-down and stop as soon as you can answer the question at hand. Depth is on demand, not by default.

1. Orient — cheap, high signal, do this first

Skim the highest-information-per-token files before any deep reading:

• README / docs/ — what the project is and does.
• Manifest (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile, …) — language, key frameworks, and the scripts (build/test/run) that show how the project is operated.
• Agent/convention files (CLAUDE.md, AGENTS.md, .cursorrules) — gotchas the maintainers already wrote down.
• Top 2–3 levels of the directory tree — names usually encode the architecture.
• Entry/config (Dockerfile, CI yaml, main.*, index.*, app.*).

Then state a one-paragraph hypothesis of the architecture before reading further.

2. Find the entry points

Locate where execution actually begins: CLI main, server bootstrap, route/handler registration, framework lifecycle hooks, or the public API surface. These anchor every later trace.

3. Search before you read

Use grep/glob on symbol names, definitions, call sites, and error strings to jump straight to the files that matter, and open only those. Reading a file end to end is a last resort — prefer the relevant function plus its immediate callers and callees.

4. Trace one real path end to end

Understanding comes from following a representative flow, not from cataloguing files — e.g. request → handler → service → data layer, or input → transform → output. Note where state lives and where boundaries are crossed (I/O, network, database).

5. Use git history when “why” matters

For surprising or “weird” code, git log -p <file> and git blame explain how it got that way far faster than guessing, and point to the commit or PR that introduced it.

6. Delegate deep dives when subagents are available

Reading many files pollutes your main context. Push broad investigations into a subagent (e.g. a read-only Explore agent) and keep only the summary. Scope each one narrowly — open-ended “investigate the codebase” burns context for little return.

Answering codebase questions

Treat them as questions for a senior engineer and answer from the code, citing path:line:

• “How does <subsystem> work?” → trace it (step 4), don’t speculate.
• “Where do I add a new <X>?” → find an existing X and name the files/pattern to copy.
• “Why does this do A instead of B?” → check git history (step 5) and the call sites.

Deliver a map, not a file dump

When reporting what you’ve learned, give a structured model the user can act on:

• What it is — one or two sentences.
• Stack & shape — language, frameworks, architectural style (monolith, layered, microservices, …).
• Layout — the few directories that matter and what each owns.
• Key flows — the main path(s) traced, as A → B → C, with the entry file:line.
• Where to look next — the right file for the user’s likely next task.
• Gotchas — non-obvious conventions, coupling, or risks you noticed.

Keep it tight and link to specifics with path:line rather than pasting large blocks.

Optionally persist the map to disk

When the user asks for a file, or the codebase is large enough that the map won’t sit comfortably in chat, write the findings to a fresh temp directory (e.g. /tmp/codebase-map-<repo>/) and tell the user the path. Two formats:

Single markdown file (<repo>-map.md) — the default. The map structure above as one document with a short table of contents. Keep path:line references as inline code so they stay greppable.

Obsidian-style linked vault — for larger or multi-subsystem codebases. Write one short note per major area/flow plus an index, connected with [[wikilinks]]:

• index.md — a map-of-content note: the one-paragraph “what it is”, the stack, and [[links]] to every other note.
• One note per subsystem or traced flow (e.g. auth-flow.md, data-layer.md), each linking to related notes with [[...]] and back to [[index]].
• Use [[wikilinks]] for concepts that have their own note; use plain path:line for source references.
• Add optional YAML frontmatter (tags, aliases) so the vault is searchable in Obsidian.

One idea per note is what makes the graph useful — keep each note focused and link generously rather than writing long notes.

Anti-patterns

• Reading directories in full or alphabetically instead of following flow.
• Describing what code “probably” does — verify, or say you’re unsure.
• Endless exploration with no question to answer — define the goal, then stop when it’s met.
• Pasting whole files into the reply; cite locations instead.