| name | exploring-code |
| description | Use the moment the next action is Grep, Glob, rg, find, cat, or opening a source file to answer "where is X", "how does Y work", a type/trait question, or to check another git branch. Returns the enclosing symbol. Do NOT use for callers/callees (tracedecay:tracing-functions). |
Exploring code
NO RAW GREP, GLOB, OR FULL-FILE READS OVER INDEXED CODE.
The graph answers first; plain tools are for what the index does not cover.
Announce: "Using tracedecay:exploring-code to ." Pick the cheapest
row below, run it, and stop when the question is answered.
Route by what you are matching
| You are matching | Call | Not |
|---|
| Literal string / regex / config key / error text | tracedecay_grep (fixed_strings for plain literals) | raw Grep/rg |
A code structure — call shape, argument order, expression form (e.g. foo($$$), if ($C) { $$$ }) a text regex cannot pin down | tracedecay_ast_grep_search (in-process AST match; then tracedecay_ast_grep_rewrite via tracedecay:editing-safely to change matches) | multi-line regex guesses |
| A symbol by exact name | tracedecay_find_exact_symbol, else tracedecay_search | Glob + open |
| A concept / "how does X work" (names unknown) | tracedecay_context (task = the question, add keywords synonyms) | Explore agent |
| A file by role or path | tracedecay_files | find/ls -R |
| Half-remembered name | tracedecay_similar | guessing greps |
| Code by shape (return type, params, async) | tracedecay_signature_search | reading modules |
| Duplicate code / similar function bodies / repeated helper logic | tracedecay_redundancy (path, min_lines, max_pairs) | name-only search |
| A trait/interface/class's full type hierarchy (implementors + extenders, recursively) | tracedecay_type_hierarchy | manually grepping impl X for / extends X |
Read cheaply — stop at the first rung that answers
- Orient in a file →
tracedecay_outline (symbols + line numbers, no bodies).
- API surface →
tracedecay_signature; per-file bulk → tracedecay_read mode:"signatures".
- One symbol's source →
tracedecay_body — never open a whole file for one function.
- A line range →
tracedecay_read mode:"lines"; whole file (last resort) →
tracedecay_read mode:"full" (cross-session cached; prefer it over Read).
- Module surface →
tracedecay_module_api.
For types and traits — tracedecay_implementations / tracedecay_impls /
tracedecay_type_hierarchy / tracedecay_derives / tracedecay_constructors
/ tracedecay_field_sites, plus tracedecay_by_qualified_name and
tracedecay_node for stable identity — read
references/types-and-traits.md.
For other git branches without switching checkout — tracedecay_branch_list /
tracedecay_branch_search / tracedecay_branch_diff — read
references/other-branches.md.
Rules
- One well-formed
tracedecay_context call beats many narrow searches. Pass
prior seen_node_ids via exclude_node_ids on follow-ups; respect the call
budget in the tool description.
- Truncated response with a
handle? Narrow the query; call
tracedecay_retrieve only if the omitted detail is needed. Never re-run broad.
- Empty or stale-looking results → check
tracedecay_status BEFORE concluding
the repo is unindexed; the index auto-syncs — do not run manual sync commands.
- Search came up empty and a new helper seems needed → run the
tracedecay:editing-safely duplicate probe first.
- Similarity by functionality/body, not just by name → run
tracedecay_redundancy before concluding no duplicate exists. Scoped hunt
recipe: path to the suspect directory, min_lines: 6,
similarity_threshold: 0.55 — whole-repo scans at defaults favor precision
and can miss real duplicates.
- "Who calls X / what does X call / what breaks" → hand off to
tracedecay:tracing-functions / tracedecay:assessing-impact after resolving
the symbol; do not grep for call sites.
- Fall back to plain Grep/Glob/Read only for non-indexed content (prose docs,
vendored/skipped trees) or after the graph pinpoints exact files.
If tools are deferred or MCP fails
- Deferred (names listed without schemas): load once with ToolSearch —
select:tracedecay_context,tracedecay_search,tracedecay_grep,tracedecay_outline,tracedecay_body,tracedecay_read,tracedecay_redundancy
(one batched call, add others needed) — then call normally.
- MCP error/timeout/disconnect: same tool, same args, via shell:
tracedecay tool <name> (see tracedecay:using-the-cli). Never
query .tracedecay databases directly; never abandon the graph over transport.
Deliverable
Do not end this workflow without: the file + symbol (path, qualified name,
signature), the snippet or outline that answers the question, and how it was
found. Budget: aim for ≤4 graph calls before synthesizing; if the answer is
still incomplete, say precisely what is missing rather than falling back to
grep. Report any tracedecay_metrics: savings line to the user.
