106 lines
2.1 KiB
Markdown
106 lines
2.1 KiB
Markdown
|
# Debug Workflow
|
||
|
|
|
||
|
|
**"Something is broken."**
|
||
|
|
|
||
|
|
## Trigger
|
||
|
|
- "Fix this bug" / "Something's broken"
|
||
|
|
- "This doesn't work" / "Error in..."
|
||
|
|
- Test failure / Unexpected behavior
|
||
|
|
|
||
|
|
## The Flow
|
||
|
|
|
||
|
|
### 1. Check Skills
|
||
|
|
```
|
||
|
|
Any relevant skills for debugging?
|
||
|
|
- Error pattern recognition skills
|
||
|
|
- System-specific diagnostic skills
|
||
|
|
- Use if helpful, skip if not
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Read Context
|
||
|
|
```bash
|
||
|
|
# Find related bead (if exists)
|
||
|
|
bd query "title~=<error-keyword> OR labels~=<component>"
|
||
|
|
|
||
|
|
# Check recent changes
|
||
|
|
bd query "updated<1d AND status=closed"
|
||
|
|
|
||
|
|
# Read related bead details
|
||
|
|
bd show <related-id>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Reproduce & Isolate
|
||
|
|
```
|
||
|
|
First question: Can I reproduce this?
|
||
|
|
|
||
|
|
If YES:
|
||
|
|
- Isolate the minimal reproduction
|
||
|
|
- Identify the exact failure point
|
||
|
|
- Gather evidence (logs, stack traces)
|
||
|
|
|
||
|
|
If NO:
|
||
|
|
- Add logging/observability
|
||
|
|
- Create hypothesis
|
||
|
|
- Design experiment to confirm
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. Root Cause Analysis
|
||
|
|
Ask "Why?" at least 3 times:
|
||
|
|
```
|
||
|
|
Symptom: Test fails
|
||
|
|
Why 1: Function returns wrong value
|
||
|
|
Why 2: Input is malformed
|
||
|
|
Why 3: Upstream normalization missing
|
||
|
|
ROOT CAUSE: Missing normalization in caller
|
||
|
|
```
|
||
|
|
|
||
|
|
**Fix the DESIGN, not just the symptom.**
|
||
|
|
|
||
|
|
### 5. Fix Implementation
|
||
|
|
```
|
||
|
|
1. Write failing test that exposes the bug
|
||
|
|
2. Implement minimal fix
|
||
|
|
3. Verify test passes
|
||
|
|
4. Check for similar bugs elsewhere (same pattern)
|
||
|
|
```
|
||
|
|
|
||
|
|
### 6. Update Memory
|
||
|
|
```bash
|
||
|
|
# Find or create bug bead
|
||
|
|
bd create "Fix: <description>" --type bug --priority P1
|
||
|
|
|
||
|
|
# Document root cause
|
||
|
|
bd update <id> --notes "Root cause: ...
|
||
|
|
Why this was possible: ...
|
||
|
|
Fix: ...
|
||
|
|
Evidence: test added, gates pass"
|
||
|
|
|
||
|
|
# Close with evidence
|
||
|
|
bd close <id> --reason "Fixed. Root cause: X. Prevention: Y."
|
||
|
|
```
|
||
|
|
|
||
|
|
### 7. Verify
|
||
|
|
```bash
|
||
|
|
npm run typecheck && npm run lint && npm run test
|
||
|
|
```
|
||
|
|
|
||
|
|
## The Debug Questions
|
||
|
|
|
||
|
|
1. What is the symptom?
|
||
|
|
2. Can I reproduce it?
|
||
|
|
3. Where does it fail?
|
||
|
|
4. Why does it fail there?
|
||
|
|
5. Why was this possible? (design flaw)
|
||
|
|
6. Does the same flaw exist elsewhere?
|
||
|
|
|
||
|
|
## Prevention Mindset
|
||
|
|
|
||
|
|
Linus doesn't just fix bugs. Linus eliminates bug CLASSES.
|
||
|
|
|
||
|
|
After every fix, ask:
|
||
|
|
- What design flaw allowed this?
|
||
|
|
- How do I prevent the entire class?
|
||
|
|
- Is there a pattern to search for?
|
||
|
|
|
||
|
|
Update bead with prevention notes for future reference.
|