AgentSkillsCN

systematic-debugging

四阶段调试方法论，强调在修复问题之前深入剖析根本原因。适用于 Bug 调查、避免随机修复，以及系统化的问题解决。基于 obra/superpowers。

SKILL.md
--- frontmatter
name: systematic-debugging
description: Four-phase debugging methodology emphasizing root cause analysis before fixes. Use for bug investigation, preventing random fixes, and systematic problem-solving. Based on obra/superpowers.
version: 1.0.0
category: development
last_updated: 2026-01-19
source: https://github.com/obra/superpowers
related_skills:
  - tdd-obra
  - writing-plans
  - code-reviewer

Systematic Debugging Skill

Overview

This skill provides a structured four-phase debugging framework emphasizing root cause discovery before attempting fixes. Core principle: "Random fixes waste time and create new bugs. Quick patches mask underlying issues."

Quick Start

  1. •Investigate - Gather evidence, reproduce consistently
  2. •Analyze - Compare with working patterns
  3. •Hypothesize - Form and test specific theories
  4. •Implement - Fix with test coverage

When to Use

  • •Bug reports requiring investigation
  • •Test failures with unclear causes
  • •Production incidents
  • •Performance regressions
  • •Integration failures
  • •Any debugging that requires more than 5 minutes

The Four Phases

Phase 1: Root Cause Investigation

Objective: Understand the problem completely before attempting any fix.

Steps:

  1. •Examine error messages thoroughly
  2. •Reproduce the issue consistently
  3. •Review recent changes (commits, configs, dependencies)
  4. •Gather diagnostic evidence (logs, traces, metrics)
  5. •For multi-component systems, add instrumentation at each boundary

Questions to answer:

  • •What exactly is failing?
  • •When did it start failing?
  • •What changed recently?
  • •Can I reproduce it reliably?

Phase 2: Pattern Analysis

Objective: Find working examples and understand differences.

Steps:

  1. •Locate working examples in the codebase
  2. •Compare against reference implementations completely
  3. •Identify differences systematically
  4. •Understand all dependencies

Key comparisons:

  • •Working vs. broken code paths
  • •Expected vs. actual behavior
  • •Known good state vs. current state

Phase 3: Hypothesis and Testing

Objective: Form and validate theories before changing code.

Steps:

  1. •Formulate a specific hypothesis
  2. •Design a test for the hypothesis
  3. •Test with minimal changes (one variable at a time)
  4. •Verify results before proceeding

Hypothesis format: "The bug occurs because [condition] when [trigger], which causes [symptom]."

Phase 4: Implementation

Objective: Fix the root cause with proper verification.

Steps:

  1. •Create a failing test case reproducing the bug
  2. •Implement a single fix addressing the root cause
  3. •Verify the test passes
  4. •Verify no other tests broke
  5. •Document the fix

Critical Safeguards

Hard Stop Rule

If >= 3 fixes fail: STOP and question the architecture.

When multiple fixes fail, the issue indicates deeper structural problems requiring discussion rather than continued symptom-patching.

Red Flags (Restart Process)

  • •Proposing solutions before investigation
  • •Attempting multiple simultaneous fixes
  • •Assuming without verification
  • •Skipping reproduction step
  • •"It should work" without evidence

Debugging Anti-Patterns

Anti-PatternProblemCorrect Approach
Shotgun debuggingRandom changes hoping something worksSystematic investigation
Printf debugging onlyIncomplete pictureStructured instrumentation
Blame the frameworkAvoids understandingVerify framework behavior
"Works on my machine"Environment assumptionsDocument exact repro steps
Quick patchHides root causeFind and fix actual cause

Instrumentation Strategies

Logging Strategy

code
1. Entry/exit of suspected functions
2. Input/output values at boundaries
3. State changes at key points
4. Timing information for performance issues

Boundary Tracing

For multi-component systems:

code
[Input] -> [Component A] -> [Component B] -> [Output]
   ^            ^               ^              ^
   |            |               |              |
 Check 1     Check 2         Check 3       Check 4

Add verification at each boundary to isolate failure point.

Best Practices

Do

  1. •Reproduce before investigating
  2. •Document investigation steps
  3. •Test one hypothesis at a time
  4. •Write regression test for every bug fix
  5. •Share findings with team
  6. •Update documentation when environment-related

Don't

  1. •Jump to conclusions
  2. •Make multiple changes at once
  3. •Fix symptoms instead of causes
  4. •Skip the hypothesis step
  5. •Merge fixes without tests
  6. •Ignore intermittent failures

Error Handling

SituationAction
Cannot reproduceGather more context, check environment differences
Multiple potential causesIsolate and test each separately
Fix breaks other thingsRevert, investigate dependencies
Root cause unclear after investigationEscalate, add more instrumentation

Metrics

MetricTargetDescription
First-fix success rate>80%Fixes that resolve issue first time
Regression rate<5%Bug fixes causing new bugs
Investigation time ratio>60%Time spent investigating vs. coding
Documentation rate100%Bugs documented with root cause

Debugging Checklist

  • • Issue reproduced consistently
  • • Recent changes reviewed
  • • Error messages fully understood
  • • Working comparison found
  • • Hypothesis documented
  • • Single-variable test performed
  • • Root cause identified
  • • Failing test written
  • • Fix implemented
  • • All tests pass
  • • Fix documented

Related Skills

Version History

  • •1.0.0 (2026-01-19): Initial release adapted from obra/superpowers