mcpField
S
systematic-debugging

systematic-debugging

github.com/vudovnDevelopment8.2k279 installsUpdated 9w ago
Repository

About systematic-debugging

systematic-debugging is a debugging skill that guides developers and AI agents through a structured investigation before making changes. Its four phases move from reproducing and isolating an issue to finding its root cause, fixing it, and verifying the result.

Key features

  1. 01四段階のデバッグ手順
  2. 02再現手順と発生頻度の記録
  3. 03切り分けと根本原因分析
  4. 04修正後の回帰確認
  5. 05デバッグ用コマンド例

Use cases

  1. 01稳定复现并记录故障
  2. 02缩小问题来源并追查根因
  3. 03修复后确认问题消失且无回归

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/vudovn/ag-kit --skill systematic-debugging

After installing, type/systematic-debuggingin Claude Code to confirm it loaded.

Details

From the project README

Systematic Debugging

Source: obra/superpowers

Overview

This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.

4-Phase Debugging Process

Phase 1: Reproduce

Before fixing, reliably reproduce the issue.

## Reproduction Steps
1. [Exact step to reproduce]
2. [Next step]
3. [Expected vs actual result]

## Reproduction Rate
- [ ] Always (100%)
- [ ] Often (50-90%)
- [ ] Sometimes (10-50%)
- [ ] Rare (<10%)
Phase 2: Isolate

Narrow down the source.

## Isolation Questions
- When did this start happening?
- What changed recently?
- Does it happen in all environments?
- Can we reproduce with minimal code?
- What's the smallest change that triggers it?
Phase 3: Understand

Find the root cause, not just symptoms.

## Root Cause Analysis
### The 5 Whys
1. Why: [First observation]
2. Why: [Deeper reason]
3. Why: [Still deeper]
4. Why: [Getting closer]
5. Why: [Root cause]
Phase 4: Fix & Verify

Fix and verify it's truly fixed.

## Fix Verification
- [ ] Bug no longer reproduces
- [ ] Related functionality still works
- [ ] No new issues introduced
- [ ] Test added to prevent regression

Debugging Checklist

## Before Starting
- [ ] Can reproduce consistently
- [ ] Have minimal reproduction case
- [ ] Understand expected behavior

## During Investigation
- [ ] Check recent changes (git log)
- [ ] Check logs for errors
- [ ] Add logging if needed
- [ ] Use debugger/breakpoints

## After Fix
- [ ] Root cause documented
- [ ] Fix verified
- [ ] Regression test added
- [ ] Similar code checked

Common Debugging Commands

# Recent changes
git log --oneline -20
git diff HEAD~5

# Search for pattern
grep -r "errorPattern" --include="*.ts"

# Check logs
pm2 logs app-name --err --lines 100

Anti-Patterns

❌ Random changes - "Maybe if I change this..." ❌ Ignoring evidence - "That can't be the cause" ❌ Assuming - "It must be X" without proof ❌ Not reproducing first - Fixing blindly ❌ Stopping at symptoms - Not finding root cause

Comments

Markdown supported