explore

Explore

Build an accurate, cited map of a codebase — or one feature/area within it — so a downstream skill can act on it. The output is understanding, not change: this skill observes and reports only and must never modify a file, run a mutating command, or write anything except its report. The bar is a map a reader can trust because every claim is either backed by a file:line reference or explicitly flagged as unverified. Scope to the topic the caller named; do not map the whole repo when asked about a slice.

Shared vocabulary

Use these terms so downstream skills that act on this map share one language:

• Interface — the surface a caller sees (signatures, exported names, public API).
• Implementation — the code behind that surface.
• Module depth — how much behavior an interface hides. A deep module hides a lot behind a small interface (good — complexity is concentrated); a shallow one exposes nearly as much as it hides (a thin pass-through that mostly relocates complexity).
• Seam — a boundary where behavior can be substituted or intercepted (an interface, a port, a dependency-injection point). Name seams explicitly; they are where plan and implement will cut.

Process

1. Detect the stack first — before asserting anything. Read the dependency/manifest files (go.mod, package.json, pyproject.toml/requirements.txt, Cargo.toml, pom.xml, Gemfile, etc.) to learn languages, frameworks, and versions, plus the build/test entry points (Makefile, CI config, scripts). Cite the file for every stack claim; if you cannot confirm a version or choice, say so rather than guessing.
2. Stage 1 — Feature/Area Discovery. Find the entry points and the files relevant to the topic. Grep for the feature's names, routes, types, and config keys; locate where execution or a request begins. List the candidate files before diving in.
3. Stage 2 — Code-Flow Tracing. Follow the call chain end to end from each entry point, through every abstraction layer, down to where data is persisted, returned, or leaves the process (DB, queue, network, file). Record the chain as file:line → file:line. Note each seam you cross and whether the module behind it is deep or shallow.
4. Stage 3 — Architecture Analysis. Step back: module boundaries, ownership (who/what owns each area — CODEOWNERS, directory structure), dependencies and their direction, and the recurring patterns and existing abstractions a consumer should reuse rather than reinvent.
5. Stage 4 — Implementation Details. Capture the specifics a consumer needs: key signatures, invariants, error/validation paths, configuration, and the build/test commands that exercise this area — each with a file:line. Identify and cite these commands; do not run them — a build or test can mutate state (codegen, dependency installs, caches, network), which this skill must not.
6. Close with the essential-files list (see below) — the compact handoff artifact. Dispatch a sub-agent per independent entry point or area when sub-agents are available; otherwise trace each inline, one at a time.