recursive-exploration

Recursive Exploration

A protocol for systematic codebase exploration, inspired by Recursive Language Modeling (RLM). Treat the codebase as external memory: trace call chains recursively, prune everything that does not serve the current step, and land changes in small, verified increments.

The codebase is the source of truth. Project files are the only evidence for project logic. Training data may be stale or simply wrong about this codebase: a file read or a search result is evidence, a recollection is not.

When to activate

• Starting a task in code you have not read
• Tracing how a change propagates through the codebase
• Planning modifications that touch multiple files or modules
• Debugging by following an execution path

Skip it when the whole change lives in a file you already read and understood in this session.

Core concepts

• Recursive tracing — before any modification, walk the call chain of the current step: consumers (who calls this?) and dependencies (what does this call?).
• Contract verification — read the source of an interface, type, or class before using it. Never assume the shape of a data structure.
• Missing definitions — when a called symbol's body is not in the repo, resolve it from documentation, its tests, or a small probe run. The identifier's name is a hypothesis, never evidence of behavior.
• Context pruning — ignore files that do not contribute to the current atomic step, to keep reasoning density high.
• Confidence threshold — when a detail sits outside your context, stop and say: "I need to see [file_path] to proceed with high confidence."

Process

1. Locate the entry point. Search with grep, find, or the agent's search tool for the feature, symbol, or error text. Search first; ask the user for a path only after searching fails. If a structural index exists (call graph, codegraph, AST tooling), rank candidate entry points with it before reading any file body, and read the symbol rather than the whole file when the tool allows. Done when: you know which file the change starts in.
2. Trace outward and inward. Follow imports and call sites to map both consumers and dependencies. Read the real definitions, not the call sites' assumptions. Done when: every consumer and dependency the current step actually touches has been read, and anything deliberately deferred is named rather than silently skipped.
3. Draw the dependency tree. Print a small tree of the files explored and the files you intend to modify. Done when: the tree has been shown to the user.
4. Reduce the change to one step. Propose exactly one logical change, with the reasoning stated before any code. Done when: the user faces a single, reviewable step.
5. Execute, verify, re-plan. Run the relevant check or test, confirm the result, then reassess whether the original plan still holds. A claim about runtime behavior requires a run, a test, or a real execution trace. Simulating the code in your head is not evidence, including for code you just wrote. Done when: the step is verified green and the next step is known — or a pivot is explained and re-planned.