AgentSkillsCN

Skill Debug

技能交接

SKILL.md

Debug Skill

This skill provides a systematic approach to debugging issues.

Usage

Invoke with /debug followed by the issue:

  • •/debug <error message> - Debug specific error
  • •/debug --trace - Enable verbose tracing
  • •/debug --hypothesis "<theory>" - Test specific hypothesis

7-Phase Debugging Framework

Phase 1: Reproduce

Goal: Consistently reproduce the issue

  • •Get exact steps to reproduce
  • •Identify minimum reproduction case
  • •Note environment details (OS, versions, config)
  • •Confirm issue is reproducible

Phase 2: Gather Information

Goal: Collect relevant data

bash
# Check logs
tail -100 [log file]

# Check recent changes
git log -10 --oneline
git diff HEAD~5

# Check environment
node --version  # or relevant runtime
npm list        # or relevant dependencies

Phase 3: Form Hypothesis

Goal: Develop theory about root cause

Based on evidence, hypothesize:

  • •What component is failing?
  • •What changed recently?
  • •What are the boundaries of the bug?

Phase 4: Test Hypothesis

Goal: Validate or invalidate theory

  • •Add targeted logging
  • •Use debugger breakpoints
  • •Create minimal test case
  • •Check assumptions

Phase 5: Identify Root Cause

Goal: Find the actual source

Common root causes:

  • •State mutation in unexpected place
  • •Race condition or timing issue
  • •Null/undefined reference
  • •Type coercion problem
  • •Configuration mismatch
  • •External service failure

Phase 6: Implement Fix

Goal: Correct the issue

  • •Fix root cause, not symptoms
  • •Consider edge cases
  • •Add regression test
  • •Document the fix

Phase 7: Verify

Goal: Confirm fix works

  • •Run reproduction steps
  • •Run test suite
  • •Check for regressions
  • •Monitor in staging if applicable

Common Patterns

"It Works on My Machine"

Check:

  • •Environment variables
  • •Node/runtime version
  • •Dependency versions (package-lock.json)
  • •OS-specific behavior
  • •File path separators

Intermittent Failures

Look for:

  • •Race conditions
  • •Timing-dependent code
  • •External service flakiness
  • •Memory leaks
  • •Resource exhaustion

Performance Issues

Investigate:

  • •N+1 queries
  • •Missing indexes
  • •Unbounded loops
  • •Memory leaks
  • •Blocking operations

"Nothing Changed"

Verify:

  • •Recent deployments
  • •Dependency updates
  • •Configuration changes
  • •External service changes
  • •Data changes

Output Template

markdown
## Debug Report: [Issue Title]

### Reproduction
**Steps**: [how to reproduce]
**Frequency**: [always / sometimes / rare]
**Environment**: [relevant details]

### Investigation

#### Hypothesis 1: [theory]
**Test**: [what I tried]
**Result**: [confirmed / rejected]

#### Hypothesis 2: [theory]
**Test**: [what I tried]
**Result**: [confirmed / rejected]

### Root Cause
[Explanation of actual cause]

### Fix
**File**: `path/to/file.ts:123`
**Change**: [description of fix]

### Verification
- [ ] Original issue no longer reproduces
- [ ] Tests pass
- [ ] No regressions observed

### Prevention
[How to prevent similar issues]

Debugging Commands

bash
# Node.js debugging
node --inspect app.js
DEBUG=* node app.js

# Check for common issues
npm ls --depth=0  # dependency conflicts
npm audit         # security issues

# Git bisect for regression
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>