debug

mcouthon 的头像作者 mcouthon

通过基于假设的调查进行系统调试。在出现故障、测试失败、出现意外行为或需要调查错误时使用。触发词包括:'这是故障'、'调试'、'为什么这个会失败'、'意外错误'、'不工作'、'错误'、'修复这个问题'、'调查'、'测试失败'、'追踪错误'、'启用调试模式'。完全访问模式 - 可以运行命令、添加日志和修复问题。

📖 中文导读:通过基于假设的调查进行系统调试。在出现故障、测试失败、出现意外行为或需要调查错误时使用。触发词包括:'这是故障'、'调试'、'为什么这个会失败'、'意外错误'、'不工作'、'错误'、'修复这个问题'、'调查'、'测试失败'、'追踪错误'、'启用调试模式'。完全访问模式 - 可以运行命令、添加日志和修复问题。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: debug description: > Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: "this is broken", "debug", "why is this failing", "unexpected error", "not working", "bug", "fix this issue", "investigate", "tests failing", "trace the error", "use debug mode". Full access mode - can run commands, add logging, and fix issues.

Debug Mode

Systematic bug investigation and resolution.

Core Approach

"Don't guess. Form hypotheses. Test them."

The 4-Phase Process

Phase 1: Assessment 🔍

Goal: Understand and reproduce

  • What is the expected behavior?
  • What is the actual behavior?
  • Can you reliably reproduce?
  • What changed recently?

Key Questions:

  • When did this start happening?
  • Does it happen consistently or intermittently?
  • What are the exact inputs that trigger it?
  • What error messages or symptoms appear?

Phase 2: Investigation 🔬

Goal: Isolate and trace

  • Trace execution from entry point
  • Identify where expected diverges from actual
  • Form hypotheses about root cause
  • Test hypotheses systematically

Techniques:

  • Add strategic logging/prints
  • Use debugger breakpoints
  • Simplify inputs to minimal reproduction
  • Check boundary conditions

Phase 3: Resolution 🔧

Goal: Fix minimally and verify

  • Implement the smallest fix that addresses root cause
  • Don't fix symptoms, fix the disease
  • Add regression test
  • Verify fix doesn't break other things

Phase 4: Quality ✅

Goal: Prevent recurrence

  • Add test covering the bug
  • Document if the cause was non-obvious
  • Consider if similar bugs exist elsewhere
  • Clean up debug code

Debugging Checklist

- [ ] **Reproduced**: Can trigger bug consistently
- [ ] **Isolated**: Know which component is failing
- [ ] **Root Cause**: Understand WHY it fails
- [ ] **Fixed**: Minimal change addresses cause
- [ ] **Tested**: Regression test added
- [ ] **Clean**: Debug code removed

Hypothesis Template

**Hypothesis**: [What you think is wrong]
**Test**: [How you'll verify]
**Result**: [What happened]
**Conclusion**: [Confirmed/Rejected/Needs more info]

Common Root Causes

Symptom Often Caused By
Works locally, fails in CI Environment differences, missing deps
Intermittent failure Race condition, timing, external dependency
Wrong output Logic error, wrong variable, off-by-one
Crash/exception Null/None access, type mismatch, missing data
Performance issue N+1 queries, missing index, memory leak

Debug Report Format

## Debug Report

### Bug Summary

- **Expected**: [what should happen]
- **Actual**: [what happens instead]
- **Severity**: [critical/high/medium/low]

### Reproduction

1. [Step to reproduce]
2. [Step to reproduce]
3. [Observe bug]

**Minimal reproduction**: [simplest case that triggers bug]

### Investigation

| Hypothesis | Test           | Result                     |
| ---------- | -------------- | -------------------------- |
| [theory]   | [what I tried] | ✅ Confirmed / ❌ Rejected |

### Root Cause

[What's actually wrong and why]

### Fix Applied

- **File**: `path/to/file.py`
- **Change**: [what was modified]
- **Why**: [how this fixes the root cause]

### Verification

- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] Regression test added: `test_name`
- [ ] No debug code left behind

### Prevention

[How to prevent similar bugs in the future]