AgentSkillsCN

systematic-debugging

采用四阶段的系统化调试方法：从边界入手追踪缺陷，收集证据，锁定根本原因，并实施加固型修复方案。绝不凭猜测行事。

SKILL.md
--- frontmatter
name: systematic-debugging
description: 4-phase systematic debugging methodology. Traces bugs through boundaries, gathers evidence, identifies root cause, and implements hardened fixes. Never guesses.

Systematic Debugging

When This Skill Activates

  • •Tests are failing
  • •User reports a bug
  • •Unexpected behavior is observed
  • •The /debug command is invoked
  • •A task executor reports a failure

CRITICAL: Never Guess

Systematic debugging is FASTER than guess-and-check thrashing. Do not:

  • •Randomly change code hoping it fixes the bug
  • •Add console.log everywhere without a plan
  • •Assume you know the cause without evidence
  • •Skip straight to "fixing" without understanding

Process

Delegate to the debugger droid:

code
Task tool → subagent_type: debugger
Provide: Bug description, expected vs actual, file paths, error messages, repro steps

The 4 Phases (executed by debugger droid):

Phase 1: Reproduce & Gather Evidence

  • •Reproduce with a concrete test or command
  • •Record exact error output, stack traces, state

Phase 2: Boundary Tracing

  • •For EACH component boundary the data crosses:
    • •What enters? What exits?
    • •Where does behavior diverge from expectation?
  • •This narrows the bug to a specific component

Phase 3: Root Cause Analysis

  • •Trace backward through the call stack
  • •Identify the ORIGINAL trigger (not just the symptom)
  • •Verify: does this root cause explain ALL observed symptoms?

Phase 4: Fix & Harden

  • •Minimum fix for the root cause
  • •Test that reproduces the bug (fails without fix, passes with fix)
  • •Defense-in-depth: add validation at multiple layers
  • •Full regression test

Sub-Techniques

Root-Cause Tracing

When you find where the bug manifests, don't stop. Trace backward:

  • •Why did this function receive bad input?
  • •Where did that bad input come from?
  • •Keep going until you find the ORIGINAL source of the problem.

Defense-in-Depth

After fixing, add validation at multiple layers:

  • •Input validation at the entry point
  • •Type assertions at boundaries
  • •Invariant checks in critical functions

Condition-Based Waiting

For async/timing bugs:

  • •Never use sleep/delay as a fix
  • •Wait for specific conditions (event fired, state changed, element visible)
  • •Add timeouts with meaningful error messages

Output

A debug report with evidence trail, root cause, fix, and hardening measures.