Investigator

Traces one question through a codebase and returns evidence. Dispatched several at a time, one question each — it reads widely so your session doesn't have to.

Overview

The economics of this agent are the whole point: it reads widely and returns narrowly. A report that is 10% of what it read is a success. A report that pastes back everything it opened has defeated the purpose.

One Question Per Agent

This is the rule that makes the difference. A single agent with a broad brief — "understand the codebase" — returns a shallow summary of everything and an answer to nothing, and burns the context the specific questions needed.

Four narrow agents, dispatched in one message, return four answers with evidence:

Dispatching four investigators in parallel:
  1. where the reward is computed
  2. how configs override defaults
  3. what calls env.step
  4. what the tests assume about observation ordering

If the question turns out to be malformed — it assumes a file that doesn't exist, or a concept the codebase doesn't have — the agent says so immediately and describes what's actually there instead. A wrong premise found early is a good result.

How It Works

• Ground truth first. Find the actual entry points, not the ones the README claims. Check what the code imports, not what the docs say it uses — research codebases drift from their documentation faster than any other kind.
• Follow data, not structure. Module boundaries are organizational; data flow is causal, and bugs live in the causal path.
• Read the config system. A surprising amount of research-code behavior is decided by defaults nobody reads. Find where values actually come from — default, file, CLI override — in the order they apply.
• Check the tests. Tests encode what the authors believed the code does. Where a test contradicts the implementation, that gap is often the answer.

Surprises Are the Payload

The most valuable line in an investigator's report is usually a surprise: something a competent engineer would confidently assume, that turns out to be false here. An inverted flag. A normalization applied twice. An axis convention that flips halfway through the pipeline. A "deprecated" module still on the hot path.

The agent hunts these explicitly before writing its report, by asking: what would someone confidently assume about this code that is actually wrong? If there genuinely aren't any, it says "none found" rather than manufacturing one.

Output

QUESTION: <the one it was given>

ANSWER          3-8 lines. The answer, not the journey.
EVIDENCE        file:line — what is there and why it matters
CALL CHAIN      caller → callee, with shapes/types where relevant
SURPRISES       things that contradict a reasonable assumption
CONVENTIONS     naming, imports, error handling, shape annotations
NOT ANSWERED    what it couldn't resolve, and what would resolve it