code-explorer

agent

Trace how an existing feature works through the code.

Called by: f-catchup f-context
On site: Optional: the foreman can use it while planning.
When: When the foreman needs to understand how an existing feature works.

It's working if

The report opens with the exploration ledger: one entry per step, each listing the files it actually opened and the file:line behind its key claim.
Anything concluded from names, docs or string matches rather than read code is listed under claims_inferred_not_verified.
The narrative cites file:line anchors instead of pasting code bodies.
It states what it searched for and did not find, and the open questions it could not settle from code.
It ends with the short list of files you need to understand the topic.
It describes the code and gives no verdict on whether something is a bug; it changed nothing.

How its report opens

The exploration ledger the agent fills before any narrative, shown exactly as the agent's instructions give it.

[
  {
    "step": "1-discovery",
    "files_examined": ["<path/to/file>", "..."],
    "evidence_anchor_for_key_claim": "<path/to/file>:<LINE>",
    "claims_inferred_not_verified": "none | <what you concluded without reading the code that proves it>"
  },
  {
    "step": "2-flow-tracing",
    "files_examined": ["..."],
    "evidence_anchor_for_key_claim": "...",
    "claims_inferred_not_verified": "..."
  },
  {
    "step": "3-architecture",
    "files_examined": ["..."],
    "evidence_anchor_for_key_claim": "...",
    "claims_inferred_not_verified": "..."
  },
  {
    "step": "4-implementation",
    "files_examined": ["..."],
    "evidence_anchor_for_key_claim": "...",
    "claims_inferred_not_verified": "..."
  }
]

Common questions

When does the foreman use it?: It is optional. While scoping or planning, the foreman may hand it bounded questions it cannot answer quickly itself, for example in /f-survey or /f-blueprint. Several explorers get questions that do not overlap.
Does it change code?: No. It has no edit, write or shell tools, and it is told not to run git commands that write.
Why does it stop before reading everything?: It reads on a budget: it maps the area first, then reads only the regions that matter. It stops as soon as it can trace the feature end to end, or when more reads only confirm what it already knows.
Can it tell me whether something is a bug?: Not as a verdict. It returns the facts with their anchors and leaves the judgement to the caller, marking anything it could not anchor as inferred.

← Used by 2

agents/code-explorer.mdThis page as Markdown