| name | ix-investigate |
| description | Deep dive into a symbol, feature, or bug. Graph-first, minimal code reads, early stopping when sufficient evidence found. |
Goal
Answer: what is this, how does it connect, and what's the execution path? Stop as soon as those three questions can be answered accurately.
If the Ix runtime is unavailable, ix_status will report this; fall back to file reads as needed.
Preferred path — unified query
For most cases, call ix_query once:
ix_query({ mode: "investigate", targets: [$ARGUMENTS] })
Use the returned preview_markdown as the primary answer. Supplement with specific tools below if needed.
Phase 1 — Locate (always)
Call: ix_locate({ symbol: $ARGUMENTS })
If no match: try ix_text({ pattern: $ARGUMENTS, limit: 10 })
Do not proceed until the entity is unambiguous.
Phase 2 — Explain (always)
Call: ix_explain({ symbol: <resolved-symbol> })
Extract: role, importance, caller count, callee count, confidence score.
Stop if: explain gave clear role, purpose, and connection summary → skip to Output.
Phase 3 — Connections (run only if caller/callee detail needed)
- If "who uses this" matters:
ix_callers({ symbol: <symbol> })
- If "what does this do internally" matters:
ix_callees({ symbol: <symbol> })
Stop if: you now know who uses it and what it depends on.
Phase 4 — Trace (run only if execution flow is unclear)
Call: ix_trace({ symbol: <symbol> })
One trace only. Pick the most representative direction.
Phase 5 — Code read (last resort only)
Only if the above steps leave a specific implementation question unanswered: read the source file at the line range from ix_locate.
Hard limit: One source read maximum.
Output
## [Symbol] — Investigation
**What it is:** [kind, file, subsystem — from graph]
**Role:** [orchestrator / boundary / helper / utility / etc.]
**Execution flow:**
[downstream: what it calls -> what those call, 2 levels max]
[upstream: who calls it, top 5]
**Key connections:**
- Depends on: [top 3 callees]
- Used by: [top 3 callers with their subsystem]
**Evidence quality:** [strong / partial / uncertain] — [one-line reason]
**Next step:**
- [most useful follow-up based on findings]