aiskillstore/flow-debugging

Flow Debugging - Systematic Debugging Method

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Bug fixing is not a guessing game. Systematic debugging = faster fixes + fewer regressions.

The 4-Phase Process

Phase 1: ROOT CAUSE INVESTIGATION (NO FIXES YET)
    ↓
Phase 2: PATTERN ANALYSIS
    ↓
Phase 3: HYPOTHESIS AND TESTING
    ↓
Phase 4: IMPLEMENTATION (TDD)

Phase 1: Root Cause Investigation

Iron Law: In this phase, NO FIX CODE ALLOWED.

Step 1: Read Error Completely
  - Don't skip any details
  - Record: error type, message, stack trace
  - Record: when it happens, frequency, impact

Step 2: Stable Reproduction
  - Find reliable reproduction steps
  - Record: inputs, environment, preconditions
  - If can't reproduce → gather more information

Step 3: Check Recent Changes
  - git log --oneline -20
  - git diff HEAD~5
  - Ask: What changed? When did it start failing?

Step 4: Trace Data Flow Backwards
  - Start from error point
  - Trace upstream
  - Find where data goes wrong

Output: Root cause hypothesis (evidence-based, not a guess)

Phase 2: Pattern Analysis

Step 1: Find Working Examples
  - Where does similar functionality work?
  - Compare: working vs broken

Step 2: Compare with Reference
  - What does official documentation say?
  - How do other projects do it?
  - What's different?

Step 3: Identify Patterns
  - Is this a known bug pattern?
  - Search: error message + framework name

Output: Confirmed or refined root cause hypothesis

Phase 3: Hypothesis and Testing

Step 1: Form Single Hypothesis
  - "The problem is because X"
  - Hypothesis must be verifiable

Step 2: Test One Variable at a Time
  - Change only one factor
  - Observe result
  - Record: what changed, what happened

Step 3: 3+ Failed Fixes → STOP
  - If 3+ fix attempts fail
  - Stop and question architecture
  - Problem may be deeper than thought

Red Flag: If you're "trying this, trying that", you're guessing, not debugging.

Phase 4: Implementation (TDD)

Prerequisite: Phases 1-3 complete, root cause confirmed

Step 1: Write Failing Test First
  - Test must reproduce the bug
  - Run test, confirm it fails
  - This is your "red light"

Step 2: Implement Single Fix
  - Fix only the root cause
  - Don't "while I'm here" other things
  - Minimal change

Step 3: Verify
  - Run test, confirm it passes
  - Run related tests, confirm no regression
  - Manual verify original issue resolved

Rationalization Prevention

| Excuse | Reality | |--------|---------| | "I know where the problem is" | Prove it. Investigate first. | | "Quick fix" | Quick fix = quick regression. Systematic debug. | | "No time for tests" | No tests = don't know if really fixed. | | "Small change" | Small changes can introduce big bugs. Test it. | | "Fix first, investigate later" | Fixing without understanding = guessing. | | "Let me try this" | "Trying" is not debugging. Form hypothesis, verify it. | | "It's obvious" | Nothing is obvious. Prove with evidence. | | "I've seen this before" | Every bug is unique. Investigate this one. |

Red Flags - STOP

If you find yourself:

• Fixing without reproduction
• "Trying this, trying that"
• 3+ failed fix attempts
• Saying "fixed" without tests
• Changing many files for one bug

STOP. Go back to Phase 1. Investigate root cause.

Debug Output Template

# Bug Analysis - ${BUG_ID}

## Phase 1: Root Cause Investigation

### Error Details
- Type: [error type]
- Message: [error message]
- Stack: [key stack frames]

### Reproduction
- Steps: [1, 2, 3...]
- Frequency: [always/sometimes/rare]
- Environment: [conditions]

### Recent Changes
- [relevant commits]

### Data Flow Analysis
- [where data goes wrong]

### Root Cause Hypothesis
[Evidence-based hypothesis]

## Phase 2: Pattern Analysis

### Working Example
[Where similar code works]

### Comparison
[Difference between working and broken]

### Confirmed Root Cause
[Refined hypothesis]

## Phase 3: Hypothesis Testing

### Hypothesis
[Single testable hypothesis]

### Test Results
| Change | Result |
|--------|--------|
| [change 1] | [result] |

## Phase 4: Implementation

### Failing Test
[Test code that reproduces bug]

### Fix
[Minimal fix code]

### Verification
- [ ] Test passes
- [ ] No regression
- [ ] Manual verification

Integration with flow-fix

This skill is the core methodology for /flow-fix command:

/flow-fix phases:
  阶段 1: Root Cause Investigation → This skill Phase 1
  阶段 2: Pattern Analysis & Planning → This skill Phase 2
  阶段 3: 修复执行 (TDD) → This skill Phase 3-4
  阶段 4: 验证与发布 → verification-before-completion

Cross-Reference

• flow-fix.md - Bug fix command
• flow-tdd/SKILL.md - TDD enforcement
• verification-before-completion - Verification skill

---

[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md