investigate · diff
git:20260228.85b621a to git:20260717.8cfac3d
30 added, 0 removed. Audit A to A.
---
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, incomplete refactor, etc.)
### If the cause is clear from reading code:
Tell the user immediately with your findings, then skip to Phase 5.
### If the cause is NOT clear from reading code:
Tell the user:
- What you've investigated so far
- Which hypotheses you've ruled out and why
- What remains unclear
Then propose diagnostic logging to narrow it down. Explain what you want to log and why, and wait for user approval before proceeding.
## Phase 4: Diagnostic Logging (Only If Needed)
Only enter this phase if Phase 3 didn't find the cause.
1. Add targeted `console.log` statements prefixed with `[DEBUG-FIX]` to the suspected code paths.
2. Ask the user to reproduce the bug and paste the relevant logs.
3. Analyze the logs:
- **Root cause identified** → tell the user what you found, then proceed to Phase 5.
- **Still unclear** → explain what you learned, refine your hypotheses, propose additional logging, and repeat with user approval.
### Escalation: When You're Stuck
If you've completed 3+ investigation cycles (hypothesis → test → inconclusive) without progress:
1. **Summarize what's been ruled out** — list every hypothesis tested and the evidence against it
2. **Propose a fundamentally different approach** — don't keep testing variations of the same theory. Consider:
- Is the bug actually in a different layer than assumed? (e.g., backend vs frontend, database vs application)
- Could this be an environment/infrastructure issue rather than a code issue?
- Is there a timing/race condition that only manifests under specific conditions?
3. **Ask the user for help** — they may have domain knowledge or context that changes the investigation direction
## Phase 5: Report and Next Steps
Once the root cause is identified, present a summary:
```
## Investigation Report
**Root cause:** [one-line summary]
**Confidence:** [High / Medium / Low] — [brief justification]
**File(s):** [affected files with line numbers]
**Introduced:** [commit hash / PR / approximate timeframe if known]
**What needs to change:**
- [description of the fix needed]
**Why this happened:**
- [brief explanation of the underlying cause — missed edge case, wrong assumption, incomplete refactor, etc.]
**Next steps:**
- `/plan [description]` — Create a fix plan
- `/simple-plan [description]` — Quick fix plan if it's straightforward
```
If diagnostic logs were added in Phase 4, remove all `[DEBUG-FIX]` logs before finishing.
## Red Flags — Catch Yourself
Stop and reassess if you notice yourself doing any of these:
- Proposing a fix before you've identified the root cause
- Making assumptions about the cause without evidence from the code
- Investigating code that has nothing to do with the reported symptoms
- Testing variations of the same failed hypothesis instead of forming a new one
- Saying "let's just try changing X and see if it works"
+ - Stacking multiple experimental changes without measuring each one independently
+ - Continuing to harden after a reliable result without preserving the known-good checkpoint
- Spending excessive time without reporting intermediate findings to the user
Bug to investigate: $ARGUMENTS