investigate

name	investigate
version	1.0
category	engineering
execution_speed	medium
token_efficiency	medium
triggers	["diagnose this","debug this","investigate this","bug","broken","performance regression"]
cache_key	investigate-1.0
dependencies	[]
disable-model-invocation	true
description	Disciplined root-cause investigation for hard bugs and performance regressions, with findings pinned to the case board. Use when user reports a bug, says something is broken/throwing/failing, describes a performance regression, or asks to diagnose/debug/investigate something.

Investigate

Replaces diagnose. Reads ${CLAUDE_PLUGIN_ROOT}/QUESTION.md for voice and ${CLAUDE_PLUGIN_ROOT}/BOARD.md for board conventions before starting.

Scope: application-layer bugs. For environment, config, or infrastructure issues, use /systematic-debugging instead.

A discipline for hard bugs. Skip phases only when explicitly justified. On start, open or create the Case note on the board.

Phase 1 -- Build a feedback loop

This is the skill; everything else is mechanical. Construct a fast, deterministic, agent-runnable pass/fail signal for the bug -- failing test, curl/HTTP script, CLI fixture diff, headless browser script, replayed trace, throwaway harness, fuzz loop, bisection harness, differential loop, or (last resort) a scripted human-in-the-loop pass. Iterate on the loop itself: faster, sharper signal, more deterministic. For non-deterministic bugs, raise the reproduction rate rather than chasing a clean repro. If you genuinely cannot build a loop, stop and say so -- list what was tried, ask for environment access, a captured artifact, or permission to add temporary production instrumentation. Do not proceed without a loop you believe in.

Phase 2 -- Reproduce

Run the loop. Confirm it produces the symptom the user described (not a different nearby failure), confirm it reproduces reliably (or at a debuggable rate), and capture the exact symptom for later verification.

Phase 3 -- Hypothesise (board-aware)

Before generating new hypotheses, search the board for Suspect notes from past Cases matching the current symptom -- surface matches as candidate hypotheses alongside fresh ones. Generate 3-5 ranked, falsifiable hypotheses ("if X is the cause, then changing Y will make the bug disappear"). Pin each as a Suspect note, wikilinked to the Case, before testing begins. Show the ranked list to the user before testing -- cheap checkpoint, don't block if they're AFK.

When pinning each Suspect note, emit a provenance node in frontmatter:

id:         spiffe://<project>/<case>/hypothesis/<slug>
asserted:   "<the falsifiable prediction>"
source:     inference
method:     inferred
confidence: unverified
verify:     "<the experiment that would confirm or rule it out>"

Cross-case recall: when surfacing a Suspect from a prior case, import with the original id intact, add #federated to tags, and inherit confidence without re-deriving it.

Phase 4 -- Instrument (evidence pinned live)

Each probe maps to a specific Suspect's prediction; change one variable at a time. Prefer debugger/REPL inspection over logs; tag any debug logs with a unique prefix for cleanup. For performance regressions, measure first (baseline + bisection) rather than logging. As results come in, log them onto the corresponding Suspect note and update its verdict (Untested -> Testing -> Confirmed / Ruled Out) live, not just at the end.

When >= 2 independent sources or instruments corroborate a Suspect prediction, update provenance to confidence: corroborated.

Gate -- stop on Confirmed

The moment a Suspect's verdict flips to Confirmed, stop. Before presenting the fix, verify the root-cause finding provenance has reached confidence: verified -- the verify: check must have passed during Phase 4 or Phase 2. Provenance is the gate precondition; user consent is its trigger. Present the verdict and the recommended fix. Wait for explicit user go-ahead before writing any fix. This gate always waits -- it guards consent for code changes, not just hypothesis ranking.

Phase 5 -- Fix + regression test

Write the regression test before the fix, but only at a correct seam -- one that exercises the real bug pattern at the call site. If no correct seam exists, that itself is the finding; note it and flag for cleanup. If a seam exists: write the failing test, watch it fail, apply the fix, watch it pass, re-run the Phase 1 loop against the original scenario.

On pass, update root-cause finding provenance to confidence: verified.

Phase 6 -- Cleanup + post-mortem

Confirm: original repro no longer reproduces, regression test passes (or seam absence is documented), all tagged debug instrumentation removed, throwaway prototypes deleted. State the confirmed hypothesis in the commit/PR message. Close the Case note with a link to the fix. Ask what would have prevented this bug -- if the answer is architectural, hand off to /improve-codebase-architecture with specifics.

Error Handling

If the board is unreachable, pinning is best-effort: run the full six-phase discipline anyway and say explicitly that the board was skipped. If Phase 3's board search turns up nothing relevant, proceed exactly as without it -- no behavior change.