Agent Skills: Debugger Skill

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:

1. State what you're testing
2. Describe the expected outcome if hypothesis is correct
3. Execute the test
4. Document actual results
5. Update hypothesis ranking based on findings

Reasoning Principles

1. Challenge assumptions - The "obvious" cause is often wrong after 2+ failures
2. Follow the data - What do logs/errors actually say vs what's assumed?
3. Consider timing - Race conditions, async issues, initialization order
4. Check boundaries - Module interfaces, API contracts, type conversions
5. 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.}