A 2-phase codebase exploration pattern that separates file discovery from file comprehension — using a cheap model to find relevant files and an expensive model to analyze them, cutting context-building costs by 50-80%.

The Pattern

Phase 1: SCOUT (cheap model)              Phase 2: EXPERT (expensive model)

Directory listings ----+                  File A contents --+
Search results --------+--> "Which files  File B contents --+--> Deep analysis,
Grep matches ----------+    are relevant  File C contents --+    architecture
File names + paths ----+    to X?"                               understanding,
                                                                 recommendations
         ~$0.001/call                          ~$0.05-0.30/call

Phase 1 (Scout). Feed directory trees, file name lists, grep results, and search matches to a cheap, fast model. Ask it: "Given this task, which files are most likely relevant?" The scout sees names and paths — never file contents. It acts like a junior developer navigating a repo: it understands naming conventions, directory structures, and common project layouts well enough to make good guesses.

Phase 2 (Expert). Read only the files the scout identified. Feed their full contents to a strong model for deep analysis — architecture understanding, bug hunting, refactoring plans, whatever the actual task requires.

Key Decisions

Names are cheap, contents are expensive. A directory listing with 500 file paths is ~2K tokens. Reading those 500 files would be ~500K tokens. The scout's job is to reduce 500 candidates to 5-15 relevant files before you pay for comprehension. Even if the scout misses one file, the cost savings from not reading the other 485 files is enormous.

Scout accuracy doesn't need to be perfect. The scout is a filter, not an oracle. You want high recall (don't miss important files) more than high precision (it's fine to include a few irrelevant files). Err on the side of including too many — the expert model can skip irrelevant content quickly. Missing a critical file is worse than reading an extra ten files.

Multiple scout passes for large repos. For repositories with thousands of files, run the scout on different subdirectories in parallel. Each scout call handles a manageable chunk. Merge their recommendations before the expert phase.

Structured output from the scout. The scout returns a JSON array of file paths with a brief rationale for each. This makes it trivially parseable and lets you audit its reasoning.

When to Use It

Unfamiliar codebases where you don't know the structure. Large repos where reading everything is impractical. Repeated exploration tasks (daily code reviews, ongoing refactoring projects) where the upfront scout investment compounds over multiple sessions. Any scenario where you're currently burning expensive model tokens on "let me look around the codebase" before getting to the real question.