systematic-debugging

name	systematic-debugging
description	Comprehensive 4-phase debugging methodology for complex bugs. Use for bugs that aren't immediately obvious or have resisted quick fixes. Keywords: bug, error, fix, debug, broken, crash, fail, exception
version	1.0.0
behaviors	["parse_error","search_code","reason","validate","write_file"]
dependencies	[]
token_estimate	{"min":1500,"typical":3500,"max":8000}

🔍 Systematic Debugging Skill

Philosophy: Understand before you fix. Verify before you celebrate.

When to Use

Use this skill when:

• Bug is not immediately obvious
• Previous quick fixes have failed
• Error involves multiple components
• Need to ensure no regression from fix
• Production issue requiring careful handling

Do NOT use this skill when:

• Bug is trivial (typo, missing import)
• Just need a quick syntax check
• Issue is really a feature request

---

Prerequisites

Before starting:

• Have access to the codebase
• Can reproduce the bug OR have error logs
• Understand the expected behavior
• Know which environment is affected

---

Process

Phase 1: ROOT CAUSE INVESTIGATION 🔬

Goal: Find the TRUE cause, not just symptoms.

Steps:

1. Reproduce the Bug

   Ask yourself:
   - Can I make this happen consistently?
   - What are the exact steps?
   - What input causes it?
   

2. Gather Evidence

   • Error messages (complete, not truncated)
   • Stack traces
   • Relevant logs
   • Recent changes (git log, blame)

3. Trace the Flow

   Start from: Error location
   Work backward: How did we get here?
   Find: Where does expected != actual?
   

4. Identify the Root Cause

   • Not "it crashed" but "WHY it crashed"
   • Not "wrong output" but "WHAT produced wrong output"

Output: Clear statement of root cause.

Red Flags (STOP if you find yourself doing these):

• ❌ Immediately jumping to code changes
• ❌ Assuming you know the cause without evidence
• ❌ Changing things randomly hoping they'll work
• ❌ Ignoring the stack trace

---

Phase 2: PATTERN ANALYSIS 📊

Goal: Understand the shape of the problem.

Steps:

1. Scope Assessment

   • Is this isolated or systemic?
   • Does it affect other components?
   • Has this happened before?

2. Similar Pattern Search

   # Search for similar patterns in codebase
   grep -r "similar_pattern" src/
   

3. Dependency Check

   • What depends on the broken code?
   • What does the broken code depend on?

4. Risk Assessment

   • What could break if we fix this?
   • Are there other places with same bug?

Output: Understanding of bug's scope and risk.

---

Phase 3: HYPOTHESIS & TESTING 🧪

Goal: Develop and test fix hypothesis.

Steps:

1. Form Hypothesis

   "If I change X to Y, then Z should work because..."
   

   Good hypothesis includes:

   • Specific change
   • Expected outcome
   • Reasoning

2. Design the Fix

   • Minimal change principle
   • Don't fix what isn't broken
   • Consider edge cases

3. Mental/Paper Test

   • Walk through the code with fix
   • Does it address root cause?
   • Any side effects?

4. Create Test Case

   • Before implementing fix, write test that fails
   • Test should pass after fix
   • Include edge cases

Output: Tested hypothesis ready for implementation.

---

Phase 4: IMPLEMENTATION & VERIFICATION ✅

Goal: Apply fix and verify it works.

Steps:

1. Implement the Fix

   • Apply minimal necessary changes
   • Add comments explaining WHY (not just what)
   • Follow project coding standards

2. Run Existing Tests

   # All tests must pass
   npm test    # or pytest, etc.
   

3. Run New Test Case

   • Test you wrote in Phase 3 should now pass
   • Verify fix addresses root cause

4. Verify No Regression

   • Related functionality still works
   • No new errors introduced
   • Performance not degraded

5. Documentation

   • Update relevant docs if needed
   • Consider adding to known issues/patterns

Output: Verified fix with passing tests.

---

Debugging Decision Tree

Bug Report Received
        │
        ▼
┌─────────────────┐
│ Can reproduce?  │
└────────┬────────┘
    YES  │  NO
         │  └──► Gather more info, check logs, ask for steps
         ▼
┌─────────────────┐
│ Error obvious?  │
└────────┬────────┘
    YES  │  NO
         │  └──► Phase 1: Root Cause Investigation
         ▼
Quick fix
         │
         ▼
┌─────────────────┐
│ Fix verified?   │
└────────┬────────┘
    YES  │  NO
         │  └──► Return to investigation
         ▼
    Complete ✓

---

Guidelines

DO ✅

• Read the full stack trace
• Reproduce before fixing
• Change one thing at a time
• Test after each change
• Keep notes during investigation
• Ask "WHY" at least 3 times

DON'T ❌

• Assume you know the cause
• Make multiple changes at once
• Skip testing
• Ignore "unrelated" errors
• Rush to deploy fix
• Delete old code without understanding it

---

Common Patterns

Pattern: Off-by-One Error

When: Array/loop issues, boundary conditions

Detection:

• Works for most cases, fails at edges
• Index out of bounds errors
• Missing first/last item

Solution:

• Check < vs <=
• Check starting index (0 vs 1)
• Verify array length handling

Pattern: Async/Timing Issue

When: Race conditions, inconsistent failures

Detection:

• Works sometimes, fails other times
• Different behavior in different environments
• Issues with "slow" operations

Solution:

• Add proper await/promises
• Check for missing error handling
• Consider operation ordering

Pattern: Null/Undefined Reference

When: Missing data, optional fields

Detection:

• "Cannot read property of undefined"
• Works with some data, not others
• Fails after recent data changes

Solution:

• Add null checks
• Use optional chaining (?.)
• Validate data at entry points

---

Anti-Patterns (AVOID)

Anti-Pattern: "It Works on My Machine"

Problem: Not investigating environment differences.

Instead:

• Compare environments systematically
• Check versions, configs, dependencies
• Document environment requirements

Anti-Pattern: "Shotgun Debugging"

Problem: Changing random things hoping something works.

Instead:

• Form hypothesis first
• Test ONE change at a time
• Keep track of what you tried

Anti-Pattern: "It's Fixed Now" (No Verification)

Problem: Assuming fix works without testing.

Instead:

• Always run tests
• Verify the exact scenario that failed
• Check for regressions

---

Success Criteria

Before claiming the bug is fixed:

• Root cause identified and documented
• Fix addresses root cause (not just symptom)
• Test case written that would catch this bug
• All existing tests pass
• New test passes
• No regressions in related functionality
• Fix is reviewable (clear, minimal, documented)
• User can verify the fix works

---

Related Skills

• skills/kilo-kit/debugging/root-cause/ - For deeper root cause analysis
• skills/kilo-kit/debugging/verification/ - For thorough verification
• skills/kilo-kit/quality/testing/ - For writing better tests

---

Systematic Debugging Skill v1.0.0 — Understand before you fix