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:

Effort Estimation

Tag recommendations by effort:

Common Failure Patterns

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.}