debugging
Systematic debugging methodologies for hard bugs. Covers rubber ducking, code tracing, hypothesis testing, logging strategies. Use when stuck on bugs that resist quick fixes.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for systematic debugging of complex software issues. It moves beyond simple fixes by implementing rigorous methodologies such as rubber ducking, code flow tracing, and hypothesis testing. By leveraging structured investigation workflows and multi-agent collaboration, it helps developers identify root causes in failure-prone areas like async operations, state mutations, and serialization boundaries, significantly reducing time-to-resolution for high-impact bugs.
Use Cases
- Case 1: Resolving intermittent or 'Heisenbug' issues by applying systematic hypothesis testing to eliminate variables and isolate the root cause.
- Case 2: Debugging complex data transformations across asynchronous boundaries where traditional step-through debugging is insufficient.
- Case 3: Utilizing 'Agent Investigation' to get unbiased, multi-perspective code reviews on unfamiliar or legacy logic to identify hidden architectural flaws.
- Case 4: Implementing a disciplined logging and cleanup workflow to diagnose production-level issues without leaving permanent technical debt in the codebase.
| name | debugging |
|---|---|
| description | Systematic debugging methodologies for hard bugs. Covers rubber ducking, code tracing, hypothesis testing, logging strategies. Use when stuck on bugs that resist quick fixes. |
| user-invocable | false |
Debugging Hard Bugs
Rubber Ducking
Quote code snippets and explain what each chunk should do vs actually does. Don't assume—verbalize the logic. Discrepancies reveal bugs.
Code Flow Tracing
Trace data from entry point to failure. At each transformation: what goes in, what comes out? Mark where expectations diverge.
Failure-prone boundaries: async, serialization, type coercion, null propagation, state mutations.
Hypothesis Testing
- List 3-5 possible causes
- List 3-5 assumptions you're making
- Test to eliminate possibilities
- Repeat until one remains
Don't change code hoping it helps—that creates noise.
Logging
Log at decision points and async boundaries, not everywhere.
Workflow:
- Add targeted logs
- Have user perform action and report output
- Diagnose and fix
- After user confirms fix works: remove all added logging
Agent Investigation
For complex/unfamiliar code sections acting as a blackbox:
- Spawn an Explore agent to trace a specific code path and report back
- Run agents in background while continuing other investigation
When stuck: Spawn 2-3 senior-advisor agents in parallel with different perspectives (pragmatist, architect, skeptic).
Avoid biasing agents: Pass them relevant file paths and the observed behavior, but not your hypotheses or assumptions. Let them form independent conclusions.
Before Fixing
- Identified exact failing line(s)?
- Understand why it fails?
If no, keep investigating.