Investigate

Investigate

One investigation, one mode. Pick the mode from the request, announce it, then run that mode's sequence. The retrieval mechanics live in the code-search skill; this skill is about which questions to ask and in what order.

Routing

Collision order: Bug > Test > Architecture > Implementation. No keyword matches → Implementation.

Announce the routing before executing it — print the query, the chosen mode, and the one-line reason. A wrong route is then correctable in one turn instead of after the investigation is spent.

Discipline that applies to every mode

• Never rank-truncate a result set. Ranking already put the important results first; cutting by line count deletes them. Narrow with scope instead.
• An error and an empty result look alike and mean opposite things. Establish which one you have before you report either.
• Name the method behind every finding. Lexical search is the right tool for exact strings, counts and filename patterns — using it is routing, not a fallback. Using it without saying so is the defect.
• Blocked, never stalled. A subagent has no tool for asking the user a question. If you cannot proceed, do not wait for an answer that cannot arrive and do not decide on the user's behalf: return a result beginning BLOCKED: naming what is missing and what would unblock it, and let the dispatching orchestrator ask.
• Centrality is relative. Treat it as tiers — core, key, ordinary, leaf — never as a number to threshold. An absent centrality means unknown, not low.

Architecture mode

Use when: "what is the architecture", "how are the layers structured", "find the design patterns", "map the system".

The highest-centrality symbols are the architecture. Start there, and skip the leaves.

Find the layers by running the same structural query against three vocabulary families and reading the file distribution of the results:

code_search(query: "controller handler endpoint route")   # presentation
code_search(query: "service business logic domain")       # business
code_search(query: "repository persistence database query") # data

Boundaries and wiring show up under interface contract abstract, inject provider module and config bootstrap initialize.

Find the patterns the same way — the pattern names are in the source:

code_search(query: "factory create builder")
code_search(query: "interface abstract contract")
code_search(query: "event emit subscribe")
code_search(query: "repository persist unit of work")

Then take the closure. Direct callers are one level; the blast radius of an architectural change is the transitive closure, grouped by depth.

find_dependents(symbol: "PaymentService")
impact(symbol: "PaymentService", max_depth: 3)

Report: detected pattern, core abstractions with their centrality tier and file:line, the layer diagram, the major flows, and the health indicators.

Persist what you derived

Architecture knowledge is expensive to re-derive and cheap to record. Write it down once derived — as bullet summaries plus file:line pointers, never pasted code. Code goes stale on the next edit; pointers survive it.

Implementation mode (default)

Use when: "how does X work", "trace the data flow", "where is X defined".

1. Locate the symbol — exact span, kind, signature, export status.
2. Inbound edges — every place that calls it. This is the impact of changing it.
3. Outbound edges — everything it calls. These are its dependencies and the data-flow path.
4. Full context when the change is non-trivial: definition plus both directions at once.

Edge kind matters as much as edge existence: call, import, extends and implements have different blast radii. Say which kind an edge is when it changes the conclusion.

Direct callers are one level. impact is the transitive closure. Refactoring decisions need the closure; a direct-caller count under-states the work every time.

Before editing: confirm the symbol resolves, confirm its current signature, think, then edit. Never grep → read → edit. Index-derived signatures are captured at index time and can lag the file — when the name is overloaded or generic, read the declaration at the returned span rather than trusting the summary.

Report: primary location with file:line, inbound edges, outbound edges, and the end-to-end flow.

Test gap mode

Use when: "what is tested", "find the coverage gaps", "audit test quality", "missing tests", "edge cases".

Tests appear in the graph as callers of the code they test. Zero test callers on code that has production callers is the high-priority case.

1. Take the inbound edges of each critical symbol.

2. Classify each caller as test or production by path, using one pattern set:

   *.test.*  *.spec.*  __tests__/  tests/
   *_test.go  *_test.py  test_*.py  src/test/java/  *_test.rs
   

3. Report both counts. Production callers > 0 and test callers = 0 is the finding worth escalating; low-centrality untested code is not a gap worth reporting.

The convention is incomplete, and the verdict must say so. Filename matching misses integration tests in non-standard locations, inline test modules (Rust #[cfg(test)]), end-to-end suites that reach the code indirectly, and any language whose convention is not in the list above. A "0 test callers" result from filename matching alone is a hypothesis, not a coverage verdict.

Two methods will disagree, and that is information. Mock registration (vi.mock, jest.mock) and generated cases (describe.each) are call sites that AST edges miss but a reference-level lookup finds. When the two counts differ, report both rather than picking one.

Report: framework, test file count, a per-function table of test callers, then the high-priority list (production callers, no test callers) and the medium list (few test callers, no error scenarios).

Bug mode

Use when: "why is X broken", "find the bug source", "root cause analysis", "trace this error".

Trace backwards through callers to find the cause; trace forwards through callees to find the effect. The full chain is the root-cause picture.

1. Locate the symbol named in the error, and take its full context.
2. Walk inbound edges outward — caller of the symbol, caller of that caller — until the chain reaches something that explains the symptom.
3. Walk outbound edges to see what the failure propagates into.
4. Take the transitive impact for post-fix verification and regression scope.

Check the type boundary explicitly. Mismatches between a symbol's actual signature and what its callers assume are a leading cause of runtime errors, and they are invisible in a call graph that only records that an edge exists. Read the declaration and read one caller.

Error origin hunting: map the error vocabulary (throw error exception), locate the error type, then take its inbound edges — whoever constructs it is where the condition is detected.

State mutation tracking: locate the mutator (set state update mutate), then enumerate who calls it.

Report: symptom → the backwards call chain → root cause with file:line → the evidence that establishes it → the count of affected locations. Every step carries its evidence; a root cause asserted without a chain is a guess.

Reading "0 callers"

Zero inbound edges has three readings, and they are not interchangeable:

1. Entry point — expected and correct. CLI mains, HTTP handlers, exported public API, test-only helpers.
2. Dead code — genuinely unreachable.
3. A call the graph cannot see — dynamic import, reflection, bracket dispatch, event or callback registration, dependency-injection wiring, or a consumer in another repository.

Never collapse the three. Report which one you concluded and the evidence for it.

This skill does not authorise deletion. A dead-code verdict needs all three of: zero inbound edges, low centrality, and not exported — an export is a public contract whose consumers may be outside this tree. Even with all three, the finding is labelled requires manual review until a human has checked it against the dynamic-dispatch list above.

High centrality with zero callers means something broke recently — a deleted call site, a botched merge — and is an investigation, not a cleanup. Low centrality with zero callers is a cleanup candidate, which is a proposal, not a verdict.