Hunt

1---2name: hunt3description: Invoke when debugging any error, crash, unexpected behavior, or failing test. Finds root cause before applying any fix. Not for code review or new features.4metadata:5  version: "3.10.1"6---7 8# Hunt: Diagnose Before You Fix9 10Prefix your first line with 🥷 inline, not as its own paragraph.11 12 13A patch applied to a symptom creates a new bug somewhere else.14 15**Do not touch code until you can state the root cause in one sentence:**16> "I believe the root cause is [X] because [evidence]."17 18Name a specific file, function, line, or condition. "A state management issue" is not testable. "Stale cache in `useUser` at `src/hooks/user.ts:42` because the dependency array is missing `userId`" is testable. If you cannot be that specific, you do not have a hypothesis yet.19 20## Rationalization Watch21 22When these surface, stop and re-examine:23 24| What you're thinking | What it actually means | Rule |25|---|---|---|26| "I'll just try this one thing" | No hypothesis, random-walking | Stop. Write the hypothesis first. |27| "I'm confident it's X" | Confidence is not evidence | Run an instrument that proves it. |28| "Probably the same issue as before" | Treating a new symptom as a known pattern | Re-read the execution path from scratch. |29| "It works on my machine" | Environment difference IS the bug | Enumerate every env difference before dismissing. |30| "One more restart should fix it" | Avoiding the error message | Read the last error verbatim. Never restart more than twice without new evidence. |31 32## Progress Signals33 34When these appear, the diagnosis is moving in the right direction:35 36| What you're thinking | What it means | Next step |37|---|---|---|38| "This log line matches the hypothesis" | Positive evidence found | Find one more independent piece of evidence to cross-validate |39| "I can predict what the next error will be" | Mental model is forming | Run the prediction; if it matches, the model is correct |40| "Root cause is in A but symptoms appear in B" | Propagation path understood | Trace the call chain from A to B and confirm each link |41| "I can write a test that would fail on the old code" | Hypothesis is specific and testable | Write the test before applying the fix |42 43Do not claim progress without observable evidence matching at least one of these signals.44 45## Hard Rules46 47- **Same symptom after a fix is a hard stop; so is "let me just try this."** Both mean the hypothesis is unfinished. Re-read the execution path from scratch before touching code again.48- **After three failed hypotheses, stop.** Use the Handoff format below to surface what was checked, what was ruled out, and what is unknown. Ask how to proceed.49- **Verify before claiming.** Never state versions, function names, or file locations from memory. Run `sw_vers` / `node --version` / grep first. No results = re-examine the path.50- **External tool failure: diagnose before switching.** When an MCP tool or API fails, determine why first (server running? API key valid? Config correct?) before trying an alternative.51- **Pay attention to deflection.** When someone says "that part doesn't matter," treat it as a signal. The area someone avoids examining is often where the problem lives.52- **Visual/rendering bugs: static analysis first.** Trace paint layers, stacking contexts, and layer order in DevTools before adding console.log or visual debug overlays. Logs cannot capture what the compositor does. Only add instrumentation after static analysis fails.53- **Fix the cause, not the symptom.** If the fix touches more than 5 files, pause and confirm scope with the user.54 55## Confirm or Discard56 57Add one targeted instrument: a log line, a failing assertion, or the smallest test that would fail if the hypothesis is correct. Run it. If the evidence contradicts the hypothesis, discard it completely and re-orient with what was just learned. Do not preserve a hypothesis the evidence disproves.58 59## Gotchas60 61| What happened | Rule |62|---------------|------|63| Patched client pane instead of local pane | Trace the execution path backward before touching any file |64| MCP not loading, switched tools instead of diagnosing | Check server status, API key, config before switching methods |65| Orchestrator said RUNNING but TTS vendor was misconfigured | In multi-stage pipelines, test each stage in isolation |66| Race condition diagnosed as a stale-state bug | For timing-sensitive issues, inspect event timestamps and ordering before state |67| Reproduced locally but failed in CI | Align the environment first (runtime version, env vars, timezone), then chase the code |68| Stack trace points deep into a library | Walk back 3 frames into your own code; the bug is almost always there, not in the dependency |69 70## Outcome71 72### Success Format73 74```75Root cause:  [what was wrong, file:line]76Fix:         [what changed, file:line]77Confirmed:   [evidence or test that proves the fix]78Tests:       [pass/fail count, regression test location]79```80 81Status: **resolved**, **resolved with caveats** (state them), or **blocked** (state what is unknown).82 83### Handoff Format (after 3 failed hypotheses)84 85```86Symptom:87[Original error description, one sentence]88 89Hypotheses Tested:901. [Hypothesis 1] → [Test method] → [Result: ruled out because...]912. [Hypothesis 2] → [Test method] → [Result: ruled out because...]923. [Hypothesis 3] → [Test method] → [Result: ruled out because...]93 94Evidence Collected:95- [Log snippets / stack traces / file content]96- [Reproduction steps]97- [Environment info: versions, config, runtime]98 99Ruled Out:100- [Root causes that have been eliminated]101 102Unknowns:103- [What is still unclear]104- [What information is missing]105 106Suggested Next Steps:1071. [Next investigation direction]1082. [External tools or permissions that may be needed]1093. [Additional context the user should provide]110```111 112Status: **blocked**