Systematic Debugging
Overview
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Anti-Rationalization Table
| Rationalization |
Reality |
| "I'll figure it out as I go" |
A structured approach saves time and reduces errors. Follow the workflow in this skill rather than improvising. |
| "I already know this topic" |
Familiarity breeds shortcuts. Use the checklist to verify you haven't missed critical steps. |
| "This doesn't apply to my situation" |
The patterns here generalize across contexts. Adapt, don't skip — the underlying principles hold. |
| "One more tool will fix it" |
Adding complexity rarely solves process gaps. Master the core workflow first. |
When to Use
Trigger phrases:
"systematic debugging"
"Any bug, test failure, or unexpected behavior"
"Performance problems"
"Build failures"
Any bug, test failure, or unexpected behavior
Performance problems
Build failures
Use especially when:
- Under time pressure
- "Quick fix" seems obvious
- Previous fix didn't work
Four Phases
- Configure before, behavior, debugging, encountering, failure settings before first use
Phase 1: Root Cause Investigation
- Read errors carefully — Don't skip warnings
- Reproduce consistently — Can you trigger reliably?
- Check recent changes — What changed recently?
- Trace data flow — Find where bad value originates
- Add diagnostics — In multi-component systems
Phase 2: Pattern Analysis
- Find working examples in codebase
- Compare against references
- Identify differences
Phase 3: Hypothesis & Testing
- Form hypothesis: "X is root cause because Y"
- Test with smallest change
- Verify before continuing
- If unknown, say "I don't know"
Phase 4: Implementation
Create failing test first
Fix ONE thing at a time
Verify fix works
If 3+ fixes failed → question architecture
- Is this pattern fundamentally sound?
- Are we "sticking with it through sheer inertia"?
- Should we refactor architecture vs. continue fixing symptoms?
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
Red Flags - STOP and Follow Process
If you catch yourself thinking:
- "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"
- "Pattern says X but I'll adapt it differently"
- "Here are the main problems: [lists fixes without investigation]"
- Proposing solutions before tracing data flow
- "One more fix attempt" (when already tried 2+)
- Each fix reveals new problem in different place
ALL of these mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (see Phase 4.5)
your human partner's Signals You're Doing It Wrong
Watch for these redirections:
- "Is that not happening?" - You assumed without verifying
- "Will it show us...?" - You should have added evidence gathering
- "Stop guessing" - You're proposing fixes without understanding
- "Ultrathink this" - Question fundamentals, not just symptoms
- "We're stuck?" (frustrated) - Your approach isn't working
When you see these: STOP. Return to Phase 1.
Common Rationalizations
| Excuse |
Reality |
| "Issue is simple, don't need process" |
Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" |
Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" |
First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" |
Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" |
Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" |
Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" |
Seeing symptoms ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) |
3+ failures = architectural problem. Question pattern, don't fix again. |
Quick Reference
| Phase |
Key Activities |
Success Criteria |
| 1. Root Cause |
Read errors, reproduce, check changes, gather evidence |
Understand WHAT and WHY |
| 2. Pattern |
Find working examples, compare |
Identify differences |
| 3. Hypothesis |
Form theory, test minimally |
Confirmed or new hypothesis |
| 4. Implementation |
Create test, fix, verify |
Bug resolved, tests pass |
When Process Reveals "No Root Cause"
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
- You've completed the process
- Document what you investigated
- Implement appropriate handling (retry, timeout, error message)
- Add monitoring/logging for future investigation
But: 95% of "no root cause" cases are incomplete investigation.
Supporting Techniques
These techniques are part of systematic debugging and available in this directory:
root-cause-tracing.md - Trace bugs backward through call stack to find original trigger
defense-in-depth.md - Add validation at multiple layers after finding root cause
condition-based-waiting.md - Replace arbitrary timeouts with condition polling
Related skills:
- superpowers:test-driven-development - For creating failing test case (Phase 4, Step 1)
- superpowers:verification-before-completion - Verify fix worked before claiming success
Real-World Impact
From debugging sessions:
- Systematic approach: 15-30 minutes to fix
- Random fixes approach: 2-3 hours of thrashing
- First-time fix rate: 95% vs 40%
- New bugs introduced: Near zero vs common
When to Use
- Any bug, test failure, or unexpected behavior
- Before proposing any fix
- When something isn't working as expected
- Performance issues or crashes
When NOT to Use
- Quick exploratory work where root cause doesn't matter
- When you're just gathering information
- For confirming known issues (already have root cause)
Common Mistakes
- Fixing symptoms instead of root cause
- Making changes without understanding why they work
- Random trial-and-error debugging
- Not documenting what you tried
- Skipping the reproduction step
- Accepting "works now" without understanding why
Red Flags
- Agent applies fixes without understanding the root cause
- Debug output is left in production code after the fix
- Watch for shortcuts and skipped steps
Verification
After completing this skill, confirm:
Process
- Analyze the task requirements
- Apply domain expertise
- Verify output quality
1---2name: systematic-debugging3description: Use when encountering any bug, test failure, or unexpected behavior,4 before proposing fixes5domain: development6author: oyi777license: Apache-2.08subdomain: software-development9tags:10- coding11- debugging12- software-engineering13- systematic14- testing15persona: "name: \"Richard Feynman\"\n title: \"The Great Explainer - Master of Root\16 \ Cause Analysis\"\n expertise: [\"Root Cause Analysis\", \"Scientific Method\"\17 , \"Problem Decomposition\", \"Hypothesis Testing\"]\n philosophy: \"The first\18 \ principle is that you must not fool yourself - and you are the easiest person\19 \ to fool.\"\n credentials:\n - \"Nobel Prize in Physics for work on quantum\20 \ electrodynamics\"\n - \"Investigated the Challenger disaster\"\n - \"Famous\21 \ for explaining complex ideas simply\"\n principles:\n - \"Write down what\22 \ you know\"\n - \"Write down what you think you know\"\n - \"Test your assumptions\"\23 \n - \"The simplest explanation is usually the correct one\"\n"24version: 1.0.025category: development26metadata:27 source: https://skillmd.com/skills/oyi77/systematic-debugging28---29303132# Systematic Debugging3334## Overview3536Random fixes waste time and create new bugs. Quick patches mask underlying issues.3738**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.3940**Violating the letter of this process is violating the spirit of debugging.**4142## The Iron Law4344```45NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST46```4748If you haven't completed Phase 1, you cannot propose fixes.495051## Anti-Rationalization Table5253| Rationalization | Reality |54|---|---|55| "I'll figure it out as I go" | A structured approach saves time and reduces errors. Follow the workflow in this skill rather than improvising. |56| "I already know this topic" | Familiarity breeds shortcuts. Use the checklist to verify you haven't missed critical steps. |57| "This doesn't apply to my situation" | The patterns here generalize across contexts. Adapt, don't skip — the underlying principles hold. |58| "One more tool will fix it" | Adding complexity rarely solves process gaps. Master the core workflow first. |5960## When to Use6162**Trigger phrases:**63- "systematic debugging"64- "Any bug, test failure, or unexpected behavior"65- "Performance problems"66- "Build failures"6768- Any bug, test failure, or unexpected behavior69- Performance problems70- Build failures7172**Use especially when:**73- Under time pressure74- "Quick fix" seems obvious75- Previous fix didn't work7677## Four Phases7879- Configure before, behavior, debugging, encountering, failure settings before first use808182### Phase 1: Root Cause Investigation83841. **Read errors carefully** — Don't skip warnings852. **Reproduce consistently** — Can you trigger reliably?863. **Check recent changes** — What changed recently?874. **Trace data flow** — Find where bad value originates885. **Add diagnostics** — In multi-component systems8990### Phase 2: Pattern Analysis91- Find working examples in codebase92- Compare against references93- Identify differences9495### Phase 3: Hypothesis & Testing961. Form hypothesis: "X is root cause because Y"972. Test with smallest change983. Verify before continuing994. If unknown, say "I don't know"100101### Phase 4: Implementation1021. Create failing test first1032. Fix ONE thing at a time1043. Verify fix works1054. If 3+ fixes failed → question architecture106 - Is this pattern fundamentally sound?107 - Are we "sticking with it through sheer inertia"?108 - Should we refactor architecture vs. continue fixing symptoms?109110 **Discuss with your human partner before attempting more fixes**111112 This is NOT a failed hypothesis - this is a wrong architecture.113114## Red Flags - STOP and Follow Process115116If you catch yourself thinking:117- "Quick fix for now, investigate later"118- "Just try changing X and see if it works"119- "Add multiple changes, run tests"120- "Skip the test, I'll manually verify"121- "It's probably X, let me fix that"122- "I don't fully understand but this might work"123- "Pattern says X but I'll adapt it differently"124- "Here are the main problems: [lists fixes without investigation]"125- Proposing solutions before tracing data flow126- **"One more fix attempt" (when already tried 2+)**127- **Each fix reveals new problem in different place**128129**ALL of these mean: STOP. Return to Phase 1.**130131**If 3+ fixes failed:** Question the architecture (see Phase 4.5)132133## your human partner's Signals You're Doing It Wrong134135**Watch for these redirections:**136- "Is that not happening?" - You assumed without verifying137- "Will it show us...?" - You should have added evidence gathering138- "Stop guessing" - You're proposing fixes without understanding139- "Ultrathink this" - Question fundamentals, not just symptoms140- "We're stuck?" (frustrated) - Your approach isn't working141142**When you see these:** STOP. Return to Phase 1.143144## Common Rationalizations145146| Excuse | Reality |147|--------|---------|148| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |149| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |150| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |151| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |152| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |153| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |154| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |155| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |156157## Quick Reference158159| Phase | Key Activities | Success Criteria |160|-------|---------------|------------------|161| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |162| **2. Pattern** | Find working examples, compare | Identify differences |163| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |164| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |165166## When Process Reveals "No Root Cause"167168If systematic investigation reveals issue is truly environmental, timing-dependent, or external:1691701. You've completed the process1712. Document what you investigated1723. Implement appropriate handling (retry, timeout, error message)1734. Add monitoring/logging for future investigation174175**But:** 95% of "no root cause" cases are incomplete investigation.176177## Supporting Techniques178179These techniques are part of systematic debugging and available in this directory:180181- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger182- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause183- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling184185**Related skills:**186- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)187- **superpowers:verification-before-completion** - Verify fix worked before claiming success188189## Real-World Impact190191From debugging sessions:192- Systematic approach: 15-30 minutes to fix193- Random fixes approach: 2-3 hours of thrashing194- First-time fix rate: 95% vs 40%195- New bugs introduced: Near zero vs common196197## When to Use198199- Any bug, test failure, or unexpected behavior200- Before proposing any fix201- When something isn't working as expected202- Performance issues or crashes203204## When NOT to Use205206- Quick exploratory work where root cause doesn't matter207- When you're just gathering information208- For confirming known issues (already have root cause)209210## Common Mistakes211212- Fixing symptoms instead of root cause213- Making changes without understanding why they work214- Random trial-and-error debugging215- Not documenting what you tried216- Skipping the reproduction step217- Accepting "works now" without understanding why218219## Red Flags220221- Agent applies fixes without understanding the root cause222- Debug output is left in production code after the fix223- Watch for shortcuts and skipped steps224225## Verification226227After completing this skill, confirm:228229- [ ] Root cause is identified and documented before applying fixes230- [ ] Debug output is removed from production code231- [ ] All required outputs generated232- [ ] Success criteria met233234## Process2352361. Analyze the task requirements2372. Apply domain expertise2383. Verify output quality