tools-only Debugger Skill
Systematic debugging methodology for diagnosing failures and root cause analysis.
When to Apply This Guidance
- 2+ failed fix attempts on the same issue
- Debugging that's gone in circles
- Complex system behavior you don't understand
- Multi-system integration problems
- Intermittent failures (Heisenbugs)
Structured Analysis Framework
Step 1: Restate the Problem
Before investigating, articulate:
- What is the actual vs expected behavior?
- What assumptions might be wrong?
- What could cause the specific symptoms described?
- Are there hidden dependencies or side effects?
Step 2: Generate Ranked Hypotheses
Always generate multiple hypotheses, ranked by likelihood:
Most Likely:
- Evidence: What supports this theory?
- Test: How to verify quickly?
Possible:
- Evidence: What partially supports this?
- Test: How to confirm or eliminate?
Unlikely but worth checking:
- Evidence: Limited, but possible
- Test: Quick check to rule out
Step 3: Systematic Verification
Test hypotheses in order. For each:
- State what you're testing
- Describe the expected outcome if hypothesis is correct
- Execute the test
- Document actual results
- Update hypothesis ranking based on findings
Reasoning Principles
- Challenge assumptions - The "obvious" cause is often wrong after 2+ failures
- Follow the data - What do logs/errors actually say vs what's assumed?
- Consider timing - Race conditions, async issues, initialization order
- Check boundaries - Module interfaces, API contracts, type conversions
- Question the environment - Config, dependencies, network, state
Decision Framework
When choosing between approaches:
| Factor | Weight | Considerations |
|---|---|---|
| Correctness | Critical | Does it actually solve the problem? |
| Simplicity | High | Prefer boring solutions over clever ones |
| Leverage | High | Use existing patterns/libraries/code |
| Developer Experience | Medium | How hard is it to debug/maintain? |
| Performance | Low* | *Unless performance IS the problem |
Effort Estimation
Tag recommendations by effort:
| Tag | Meaning | Example |
|---|---|---|
| [Quick] | <30 min | Add logging, check config |
| [Short] | 30min-2hr | Refactor function, add test |
| [Medium] | 2hr-1day | New component, integration |
| [Large] | >1 day | Architecture change |
Common Failure Patterns
| Pattern | Signal | Investigation Focus |
|---|---|---|
| Fix-break cycle | Each fix causes new problem | Root cause analysis - treating symptoms not cause |
| Confusion | "I don't understand why X happens" | Add logging, trace execution path |
| Tradeoff paralysis | Multiple valid approaches | Use decision framework above |
| Integration hell | System A + B don't work together | Interface contracts, data formats |
| Heisenbug | Works sometimes, fails randomly | Timing, state, race conditions |
Traps to Avoid
- Premature fixing - Understand before changing
- Single hypothesis - Always consider alternatives
- Assuming correctness - Verify each component independently
- Ignoring evidence - If data contradicts theory, update theory
- Scope creep - Fix the bug, not everything around it
Output Template
When debugging, structure findings as:
## Problem Understanding
{Restate in own words. Challenge framing if wrong.}
## Hypotheses (Ranked)
1. Most Likely: {hypothesis} - Evidence: {support} - Test: {verification}
2. Possible: {hypothesis} - Evidence: {support} - Test: {verification}
3. Unlikely: {hypothesis} - Evidence: {limited} - Test: {quick check}
## Recommended Approach
{Specific next steps. Be prescriptive.}
## Traps to Avoid
{What NOT to do for this specific problem.}