investigate

When to use this

• A question: how, why, or where something works, what a module does, which approach fits.
• A symptom: unexpected behavior without a clear failing signal to fix directly.

Not for a request to change code: that's a plan or a direct edit.

A plan goes through plan mode (/plan).

Procedure

0. Resolve external context. If the arguments contain a URL with little inline description, resolve it before anything else: identify the service from the domain, find its fetch tool with ToolSearch (app.clickup.com -> ClickUp tools, notion.so -> Notion, github.com -> gh or the GitHub tools), call it, and take the scope and requirements from what comes back. The resolved text becomes the effective arguments. Never hand a bare link to a subagent.

1. Classify the input as a question or a symptom. For a symptom, confirm observed behavior, expected behavior, entry point, and known repro steps; if observed vs expected is still missing, ask before continuing.

Question

2. Skim: project CLAUDE.md, rg for the names involved, read the matched sections. Answer from what was read, citing file:line, each claim labelled per rules/evidence.md section 1.
3. Only when the question spans 2-4 unfamiliar areas, fan out one built-in Explore subagent per area in a single message. Re-verify each result's decisive claim before using it (rules/subagents.md section 2). One of the areas is the cheapest option, per rules/change.md section 7.

Symptom

2. Delegate fault localization to the debugger agent (subagent_type: kit:debugger, foreground). It has no MCP tools, so its prompt carries fully resolved text, never a link. It follows:
   • Reproduce with the narrowest command; 3 attempts before calling it non-deterministic.
   • git log -10 --oneline -- <affected paths>; a commit aligned with onset is the prime suspect.
   • Trace from the entry point to where observed diverges from expected; stop at library boundaries; cap at 10 files.
   • State one hypothesis ("caused by X in file Y at line Z") before checking it.
   • Probe least-invasive first: read closer, run an existing test, git bisect, then one reverted log line or assertion.
   • Max 3 hypothesis cycles; if exhausted, report what was ruled out.

3. Across a dependency boundary, name misuse vs defect per rules/evidence.md section 3.

Output

• Short answer: inline, first line is the answer.

• Symptom, or a question that needed a fan-out: a report at the path kit scratch-dir debug <scope-slug> or kit scratch-dir explore <scope-slug> prints, then the reply rules/output.md section 3 describes, its headline the root cause or answer in one sentence.

# <Debug|Explore>: <one-line description>

Generated: <ISO timestamp>
Scope: <entry point or area>

## Observed vs expected (symptom) / Question

## Findings

<file:line citations, each labelled verified / likely / hypothesis / unknown>

## Hypotheses (symptom)

1. <hypothesis> -> <confirmed / ruled out / inconclusive>

## Root cause / Answer

## Next step

<a one-line fix to make directly, or "plan it: <scope>">

Questions the requester can answer: rules/workflow.md section 4.

Plan mode

Outside plan mode, stop at findings. In plan mode, the findings feed the plan file instead of a separate report.

Stop

• Never edit source.

• The one exception is the debugger's single reverted probe.

• Scope growing beyond the question or entry point: surface and ask.
• Root cause in a dependency or external system: document the boundary and stop.