| name | hyper-debug |
| description | Use when encountering a test failure, exception, regression, or unexpected behavior — before proposing fixes. Also when the user invokes /hyperclaude:hyper-debug. Forms hypotheses systematically instead of guess-and-check thrashing. |
hyper-debug
Debugging discipline tailored to this author's preferences.
Skip when
- You already know the exact line and exact fix (typo, missing import, obvious null check). Just fix it.
- The "bug" is a one-character correction that doesn't merit a hypothesis.
If you catch yourself rationalizing ("the cause is probably X, let me just try…") — that's hypothesis stacking. Run the cycle.
The cycle
- Reproduce. Smallest possible repro. If you can't reproduce, you can't debug.
- State the expected vs actual. Two sentences. "I expected X. I got Y."
- Hypothesize one cause. One. Not five. Pick the most likely.
- Predict what would prove the hypothesis right or wrong before running anything. "If hypothesis is correct, X should happen."
- Run the experiment. Compare to prediction.
- If wrong, hypothesize again. New hypothesis. Don't stack them.
- Once cause is confirmed, write a failing test that captures the bug before fixing — so it doesn't regress silently later.
- Fix. Run. Commit.
Anti-patterns
- Hypothesis stacking — trying five "fixes" at once and not knowing which one worked.
- Skipping the regression test — "the fix is obvious, no test needed." Write the test.
- Logging-only debugging — endless
console.log without forming hypotheses. Logs serve a hypothesis, not the other way around.
- Reading code top-to-bottom — start at the failing assertion and walk backward, not forward.
When to escalate
If after 2-3 hypotheses you still don't know the cause, stop iterating. Re-read the error message slowly, check if your repro is actually exercising the buggy code, or take a 5-minute break — you have a wrong assumption somewhere upstream.
