aiskillstore 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