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:

code

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