/investigate

name: investigate
description: Investigates bugs through hypothesis-driven root cause analysis. Automatically invoked when the user reports a bug, error, broken behavior, or something not working as expected. Use when something is broken, failing, or behaving unexpectedly.
argument-hint: "[bug description, error message, or unexpected behavior]"

Investigate Agent

Investigate this bug, find the root cause, and report back to the user.

**Principle:** Your job is to find and explain the problem — not to fix it. Do not make code changes unless adding diagnostic logs (and only with user approval).

Phase 1: Understand the Bug

If not provided in $ARGUMENTS, ask for:

• Expected behavior
• Observed behavior
• Steps to reproduce

Categorize the Bug Type

Classify the issue early — different types need different investigation strategies:

| Category | Investigation Strategy | |---|---| | **Type / Compilation Error** | Check recent type changes, inference chains, tsconfig, package versions | | **Logic Error** | Trace data flow, check conditionals, compare with working code paths | | **Race Condition / Timing** | Look for shared state, async patterns, missing awaits, event ordering | | **State Management** | Trace state mutations, check store subscriptions, verify update propagation | | **Integration / API** | Check API contracts, data transformations, request/response shapes | | **Environment / Config** | Check env variables, config files, dependency versions, build settings | | **UI / Rendering** | Check component props, conditional rendering, CSS specificity, hydration |

Verify Reproduction

Before investigating:

• Confirm you understand how to trigger the bug
• Note whether it's consistent or intermittent
• If reproduction requires a running application, flag this to the user — you may need them to reproduce and provide logs

Phase 2: Form Hypotheses

**Before reading any code**, generate 3-5 possible causes ranked by likelihood based on the bug description, error messages, and your knowledge of common failure patterns.

Format:

Hypotheses (ranked by likelihood):
1. [Most likely cause] — because [reasoning]
2. [Second most likely] — because [reasoning]
3. [Third most likely] — because [reasoning]
...

This prevents tunnel-vision on the first plausible explanation. You will test these systematically.

Phase 3: Investigate the Root Cause

Now trace through the code to test your hypotheses. Use `Explore` or `codebase-explorer` agents for broad searches and read files directly for targeted analysis.

Investigation Techniques

Use these in order of effectiveness:

1. **Start from the error and trace backward** — follow the call stack from the symptom to its origin 2. **Check recently modified files first** — most bugs exist in recently changed code. Use `git log --oneline -20 -- [relevant paths]` to find recent changes 3. **Compare working vs broken** — find similar working code in the codebase and list ALL differences between the working and broken paths 4. **Trace data flow across boundaries** — follow data transformations across service/component boundaries (API → service → repository, or parent → child → grandchild) 5. **Check git blame/log** — find the commit that introduced or changed the broken behavior

Falsifiable Experiment Loop

When inspection alone cannot prove the cause and the real runtime surface is available, turn each hypothesis into a controlled experiment:

1. **State one falsifiable claim** — describe the exact cause or behavior the experiment will support or refute. 2. **Define the signal first** — name the observable pass/fail metric: screenshot state, log sequence, raw buffer marker count, persisted row, network response, process state, or another concrete output. 3. **Isolate the runtime** — use a fresh profile, database, temporary repository, port, or process namespace so existing state cannot contaminate the result. 4. **Capture the baseline** — reproduce the failure and save the same evidence that will be collected after the experiment. 5. **Change one variable** — use the smallest diagnostic or implementation change that distinguishes this hypothesis from the alternatives. 6. **Drive the real surface** — exercise the application through the CLI, socket, browser, desktop window, or TUI rather than calling an internal function directly. 7. **Capture multiple layers** — combine user-visible evidence with logs and authoritative raw or persisted state when available. 8. **Classify the result** — mark the hypothesis supported, refuted, or inconclusive and state why the evidence reaches that conclusion. 9. **Revert failed experiments immediately** — do not stack unproven changes or let an inconclusive attempt become part of the next experiment. 10. **Update the experiment ledger** — record the hypothesis, single variable, command or driver, evidence paths, and verdict before starting the next loop.

If implementation changes have not been authorized, limit experiments to diagnostics or disposable external fixtures and report the candidate change instead of keeping it.

Freeze the First Reliable Result

Once a candidate passes the original reproduction:

• Record the exact diff or checkpoint that passed.
• Rerun the original flow from fresh isolated state.
• Probe the nearest regression surfaces and one negative or stress case.
• Preserve that known-good checkpoint before optional hardening.
• Treat each hardening change as a new hypothesis with its own measurable failure signal and revert it if the runtime evidence regresses.
• Stop expanding the solution when the stated acceptance criteria and adjacent probes pass; move broader architecture work into a separate follow-up.

What to Look For

• **What's wrong** — the specific code causing the incorrect behavior
• **When/how it was introduced** — the commit, PR, or change that broke things
• **Why it happened** — the underlying reason (missed edge case, wrong assumption, inc