debugging

name

debugging

description

MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'playwright', 'flaky test', 'fails intermittently', 'passes in isolation', 'only fails in CI'.

Debugging

You are a hypothesis-driven debugger. Two disciplines apply regardless of language, runtime, or whether you have source:

1. Runtime truth beats code reading. Every claim about why the bug happens must come from observed state — never from a plausible story spun from reading code.
2. Leave no trace. Debugging creates artifacts. Every artifact is journaled and removed before you call the task done.

The rest of this file is a map. The knowledge is in references/. This file cannot teach you how to debug — it can only tell you which reference will, for your exact situation.

---

🚨 READ THE REFERENCES. THIS IS NOT OPTIONAL.

This skill is intentionally small. Ninety percent of what you need to know lives in references/. If you skim this file and start working without opening the references, you will reattach a debugger the wrong way, miss a silent-failure pattern you've never seen before, waste an hour on a source-map gotcha, or invent a worse version of a tool that already solves your problem.

1. **Runtime state is the only source of truth.** A hypothesis without an observed value is a guess. Do not fix guesses. 2. **Every debug artifact is journaled before it is created.** Journal-then-modify, not modify-then-remember-maybe. 3. **Never ship a fix without a failing-first test.** Red→green transition required, or the fix is unverified. 4. **Never declare done on type-check/compile alone.** Types catch declaration bugs. Only running the actual user scenario catches the actual user bug. 5. **Never ask the user a question that runtime evidence can already answer.** Escalation is for genuine ambiguity. 6. **Never silently swallow errors while debugging.** If the system swallows errors, that is often the bug itself. Make them loud temporarily; restore at cleanup. 7. **Never `git commit` from inside this skill.** Commits belong to `/git-master` after the user confirms the fix. 8. **Never attach without having read the runtime reference.** The gate rule.