v1.0.0 to v1.0.0

---

name: explore-codebase

description: >-

Use when arriving at an unfamiliar codebase, or an unfamiliar region of a known one, and the

question is "what is here and how is it arranged" rather than "where is this specific thing".

Trigger phrases: "help me understand this repo", "what does this project do", "where does X

live", "walk me through the architecture", "I'm new to this codebase", "what are the main

modules". Not for tracing one symptom to its cause — that is `debug-issue`; not for judging a

diff — that is `review-changes`. Reach for this one when orienting, and switch to those once

you know where to look.

version: 1.0.0

author: ai-badger, after the code-review-graph skill templates

license: MIT

platforms: [linux, macos, windows]

metadata:

hermes:

tags: [exploration, architecture, orientation, onboarding]

related_skills: [debug-issue, review-changes, refactor-safely]

---

# Explore codebase

Orient before reading. The failure this skill exists to prevent: opening files in the order a

search engine returned them and calling the resulting impression an understanding.

The workflow derives from the skill templates the `code-review-graph` project auto-installs

(MIT, © 2026 Tirth Kanani), rewritten here to be tool-agnostic: every step carries a baseline

that needs no graph server.

## Steps

1. **Establish the shape before the content** — how large, what languages, how many entry

points.

Accelerated: a graph-stats call (e.g. `list_graph_stats`-shaped; discover the real tool name

from the server's own listing). Baseline: `git ls-files | wc -l`, `cloc` or

`git ls-files | sed 's/.*\.//' | sort | uniq -c | sort -rn` for the language split, and the

project's own manifest (`package.json`, `*.csproj`, `pyproject.toml`) for its declared

dependencies and entry points.

2. **Find the module boundaries the project actually has**, not the ones its directory names

suggest.

Accelerated: an architecture-overview or community-listing call (e.g.

`get_architecture_overview`-shaped) clusters by real coupling. Baseline: read the top-level

directory tree, then check it against the imports — a directory whose files import mostly

from one other directory is one module wearing two names.

3. **Read the entry points first.** A `main`, an HTTP route table, a CLI command registry, a

message consumer, a scheduled job. These are where the project states what it is for.

Accelerated: a flow listing (e.g. `list_flows`-shaped) names the paths the project itself

considers significant. Baseline: grep for the framework's entry-point markers — route

decorators, `if __name__ == "__main__"`, `Main(`, `.MapGet(`, a `bin` or `scripts` entry in

the manifest.

4. **Follow one real path end to end** before reading anything else. One request, one command,

one message — from entry point to persistence and back.

Accelerated: a flow query (e.g. `get_flow`-shaped) returns the whole path in one call.

Baseline: read each hop in sequence. One traced path teaches more than ten skimmed files,

because it shows which abstractions the project actually uses rather than which it declares.

5. **Locate the tests for that path.** They are the executable description of intended

behaviour, and their absence is itself a finding worth recording.

Accelerated: a tests-for query (e.g. `query_graph`-shaped with a tests-for pattern).

Baseline: search for the symbol's name under the test directory, and check whether the

project's test command names a coverage report you can read instead.

6. **Write down what you concluded and what you did not check.** An exploration that produces

no artifact has to be repeated by the next person, including you next week.

## Gotchas

No environment-specific gotchas known.

## Red flags — STOP

- Reading files in search-result order and calling it an understanding

- Describing the architecture from directory names, without checking the imports against them

- Skipping step 4 — a traced path is the difference between knowing the layout and knowing the

system

- Reporting "the codebase does X" from a region you did not open; say which parts you read

- Treating a generated or vendored directory as authored code — check whether it is in

`.gitignore` or carries a generation banner before drawing conclusions from it

An orientation is not finished until it names the entry points, one traced path, where that

path's tests live, and — explicitly — the regions left unread.