version: "1.0.0" name: exploring-a-codebase description: Use when starting work in an unfamiliar repository, when locating code across many files, or when a project's code map or architecture notes look stale.

Exploring a codebase

Live search is the primary tool. Grep and glob read the code as it is right now; every map is a snapshot that started decaying when it was written.

The published evidence for repo maps is thin and contested, and the well-attested failure is a stale map confidently pointing an agent at code that moved. Treat any map as a hint, never as a source of truth.

Two artifacts, one hard line

A project may have either, both or neither. The paths are the ones /vvkit:onboard scaffolds; elsewhere, look for an ARCHITECTURE.md, a docs/ directory, or a map a tool generates.

If a repo has a hand-written file describing its directory tree, that file is a liability. The information is derivable, so it is duplicated; being duplicated, it drifts.

Order of operations

1. Read the generated map if there is one. It is cheap and ranks the codebase by what is actually

referenced.

1. Read the architecture constraints if there are any. Layering rules, frozen names, generated

files. These are the things that get you in trouble precisely because they are invisible in the file you are editing.

1. Then search. The map tells you which types matter; grep tells you where they are used today.

Matching the tool to the question

Know what you are looking for before opening a file. On anything large, locate the section first rather than reading it whole.

History answers "why is this here"

Grep tells you what the code is. History tells you why, and it is the only source that does — the alternative is guessing at intent and calling it context.

Two traps worth knowing before you trust the answer:

• Blame points at the last toucher, not the author of the logic. A reformat, a rename, or a

license header sweep resets it for the whole file. -w ignores whitespace and -C follows code moved between files; without them you will attribute a decision to whoever ran the formatter.

• Bisect names the commit that exposed a defect, not always the one that introduced it — see

vvkit:debugging-systematically, which also covers automating the predicate.

A commit message that explains a constraint is worth more than the architecture note that paraphrased it, because it is dated and attached to the change that made it true.

When a map or doc contradicts the code

The code wins, every time. Then fix the artifact in the same change:

• A wrong generated map means the generator is stale — regenerate it, do not edit it.
• A wrong architecture note means a human claim expired — correct it, and say so in your summary.

Silently working around a wrong document leaves it wrong for the next reader, who will trust it exactly as much as you did.

Verify before you assert

Before writing any convention into a document others will trust:

A claim that fails its check gets reported, not written.