Systematic Debugging Skill Skill

Systematic Debugging Skill

Core Principle: No fixes without root cause investigation first.

The 3+ Fix Rule

[!CRITICAL] If you have attempted 3 or more fixes without success, STOP. This indicates an architectural problem, not an isolated bug. Escalate to user with analysis.

Four Phases

Phase 1: Investigate

Before attempting ANY fix:

| Action | Purpose | |--------|---------| | Read error messages completely | Errors tell you what's wrong | | Reproduce the issue | Confirm you're fixing the right thing | | Check recent changes | What changed before it broke? | | Trace data flow | Follow the data from input to error | | Gather diagnostic evidence | Logs, stack traces, state dumps |

Output: Clear statement of what's happening and where

Phase 2: Analyze

Compare broken state to working state:

| Action | Purpose | |--------|---------| | Find working examples | What does correct behavior look like? | | Compare differences | What's different between working and broken? | | Check assumptions | What are you assuming that might be wrong? | | Review dependencies | What does this code depend on? |

Output: List of differences between working and broken states

Phase 3: Hypothesize

Form a specific, testable hypothesis:

| Good Hypothesis | Bad Hypothesis | |-----------------|----------------| | "The null check on line 42 doesn't handle undefined" | "Something's wrong with the data" | | "The API returns 404 when ID contains spaces" | "The API is broken" | | "State updates before render completes" | "It's a timing issue" |

Test minimally: Change ONE thing to test the hypothesis

Output: Specific hypothesis with test plan

Phase 4: Implement

Only after phases 1-3:

Write failing test that demonstrates the bug
Implement single fix addressing root cause
Verify fix works
Verify no regressions (run full test suite)

Output: Fix with evidence it works

Red Flags: Restart the Process

If you catch yourself doing any of these, STOP and restart from Phase 1:

| Red Flag | What's Wrong | |----------|--------------| | Guessing at fixes | Skipped investigation | | "Let me try this..." | No hypothesis | | Multiple changes at once | Can't isolate cause | | "One more fix should do it" | Sunk cost fallacy | | Pretending to understand | Incomplete analysis |

The 3+ Fix Escalation

After 3 failed fix attempts:

┌─────────────────────────────────────────────┐
│ 3+ Fix Attempts Failed                       │
├─────────────────────────────────────────────┤
│ This pattern indicates:                      │
│ - Fundamental design problem                 │
│ - Missing understanding of the system        │
│ - Wrong level of abstraction                 │
│                                              │
│ Recommended actions:                         │
│ 1. Document what was tried                   │
│ 2. Describe current understanding            │
│ 3. Identify knowledge gaps                   │
│ 4. Escalate to user/architect                │
└─────────────────────────────────────────────┘

Debugging Report Template

After investigation, report:

issue:
  symptom: "[What the user sees]"
  location: "[File:line or component]"
  reproducibility: "[Always/Sometimes/Rarely]"

investigation:
  error_message: "[Exact error]"
  stack_trace: "[Relevant frames]"
  recent_changes: "[What changed]"
  data_state: "[Relevant data at failure point]"

analysis:
  working_comparison: "[What works vs what doesn't]"
  differences_found:
    - "[Difference 1]"
    - "[Difference 2]"
  assumptions_checked:
    - "[Assumption]: [Valid/Invalid]"

hypothesis:
  statement: "[Specific hypothesis]"
  test_plan: "[How to test]"
  test_result: "[What happened]"

fix:
  change: "[What was changed]"
  verification: "[How verified]"
  regression_check: "[Test results]"

Integration with Orchestration

This skill is invoked when:

orchestration detects 3+ failed fix attempts
User explicitly requests debugging help
verification skill repeatedly fails

Chain: orchestration → (3+ failures) → systematic-debugging → executor

Deviation Logging

Skipped debugging logged:

- id: [auto]
  timestamp: [now]
  expected: "Systematic debugging after 3+ failures"
  actual: "Continued attempting fixes without investigation"
  root_cause: skipped_debugging
  fix: |
    Enforce systematic-debugging skill after 3 failures.
    Add counter to orchestration skill.

Agent Skills: Systematic Debugging Skill

Install this agent skill to your local

Skill Files