Systematic Debugging

Systematic Debugging

When to Use Me

Use me when:

• fix bug
• debug
• test failing
• error
• unexpected behavior
• not working
• investigate
• why is this broken
• what's wrong
• trace this
• find the cause

Do not use me for:

• write test first
• TDD
• already investigated
• clear solution
• quick fix
• just try this
• I know the fix
• general programming questions
• installation or troubleshooting
• framework-agnostic code help

Workflow

1. Phase 1: Root Cause Investigation - Read errors, reproduce, check changes, gather evidence, trace data flow
2. Phase 2: Pattern Analysis - Find working examples, compare against references, identify differences
3. Phase 3: Hypothesis and Testing - Form single hypothesis, test minimally, verify before continuing
4. Phase 4: Implementation - Create failing test case, implement single fix for root cause, verify
5. If 3+ fixes failed: STOP and question architecture

Error Handling

• Quick fix for now: STOP, return to Phase 1
• Multiple changes at once: STOP, require single hypothesis
• Skip the test: STOP, require failing test first
• One more fix attempt (after 2+): STOP, question architecture
• I see the problem: STOP, seeing symptom != understanding root cause
• Pattern says X but I'll adapt: STOP, read reference completely

Tools

The following tools are available to assist with systematic debugging:

• wait-for - Wait for conditions instead of using arbitrary delays
• find-flaky-tests - Detect tests that pollute global state
• trace-root-cause - Analyze stack traces to identify root cause
• debug-session - Track debugging progress through 4 phases

These tools integrate with the systematic-debugging skill to automate error analysis and root cause detection.

Quick Tests

Should trigger:

• Fix this bug
• Tests are failing
• Getting this error
• Debug why login fails
• Why isn't this working
• Trace this issue

Should not trigger:

• Write a test for this feature
• Refactor this code
• Add documentation
• I already found the root cause
• Just change X and see

Functional:

• Debug a failing test systematically
• Find root cause of error

References

• references/workflow-playbook.mdx - Complete 4-phase debugging process
• references/root-cause-tracing.mdx - Trace bugs backward through call stack
• references/defense-in-depth.mdx - Multi-layer validation
• references/condition-based-waiting.mdx - Wait for conditions, not timing
• references/visual-web-debugging.mdx - Visual debugging with Playwright for webapps
• scripts/find-polluter.sh - Find tests that pollute global state
• scripts/condition-based-waiting-example.ts - TypeScript implementation

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

Red Flags - STOP and Follow Process

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "Skip the test, I'll manually verify"
• "It's probably X, let me fix that"
• "I don't fully understand but this might work"
• Proposing solutions before tracing data flow
• "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to Phase 1.

Quick Reference