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

debugger