Hunt: Diagnose Before You Fix
Prefix your first line with 🥷 inline, not as its own paragraph.
A patch applied to a symptom creates a new bug somewhere else.
Do not touch code until you can state the root cause in one sentence:
"I believe the root cause is [X] because [evidence]."
Name 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.
Rationalization Watch
When these surface, stop and re-examine:
| What you're thinking | What it actually means | Rule |
|---|---|---|
| "I'll just try this one thing" | No hypothesis, random-walking | Stop. Write the hypothesis first. |
| "I'm confident it's X" | Confidence is not evidence | Run an instrument that proves it. |
| "Probably the same issue as before" | Treating a new symptom as a known pattern | Re-read the execution path from scratch. |
| "It works on my machine" | Environment difference IS the bug | Enumerate every env difference before dismissing. |
| "One more restart should fix it" | Avoiding the error message | Read the last error verbatim. Never restart more than twice without new evidence. |
Hard Rules
- Same symptom after a fix is a hard stop. The previous hypothesis was wrong. Re-read the execution path from scratch.
- After three failed hypotheses, stop. Surface to the user: what was checked, what was ruled out, what is unknown. Ask how to proceed.
- Never state environment details from memory. Run detection first:
sw_vers,xcodebuild -version,node --version,rustc --version. State the actual output. - 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.
- 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.
- 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.
- Fix the cause, not the symptom. If the fix touches more than 5 files, pause and confirm scope with the user.
- Verify target before editing. Before modifying any file, grep to confirm the function, variable, or code path exists at the expected location. If grep returns nothing, re-examine the execution path. Do not edit based on memory.
- Never reference what does not exist. Before calling a function or using an identifier in a fix, grep the codebase to verify it exists. No results = do not use it. Create it explicitly first or choose an identifier that does exist.
- If you catch yourself writing a fix before finishing the trace, or thinking "let me just try this," stop.
Confirm or Discard
Add 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.
Gotchas
| What happened | Rule |
|---|---|
| Patched client pane instead of local pane | Trace the execution path backward before touching any file |
| Same error after 4 patches, each burying the real cause | Same symptom = stop and re-read the whole execution path from scratch |
| Diagnosed "macOS 26 beta," it was a stable release | Run sw_vers first; never state versions from memory |
| MCP not loading, tried WebFetch instead of diagnosing | Check server status, API key, config before switching methods |
| Wrote the fix before finishing the trace | "Let me just try this" = incomplete hypothesis. Stop. |
| Restarted 8 times without reading the actual error response | Read the last error verbatim before restarting |
| Orchestrator said RUNNING but TTS vendor was misconfigured | In multi-stage pipelines, test each stage in isolation |
Used format_size (nonexistent), should have been bytes_to_human | Grep for the function name before writing a call to it |
Outcome
Root cause: [what was wrong, file:line]
Fix: [what changed, file:line]
Confirmed: [evidence or test that proves the fix]
Tests: [pass/fail count, regression test location]
Status: resolved, resolved with caveats (state them), or blocked (state what is unknown).