diegosouzapw Bugfix
Intelligently diagnose and fix bugs through a systematic, evidence-based approach that prioritizes understanding over guessing.
When to Use
- Production bug reports where root cause is unclear
- Intermittent failures that are hard to reproduce
- Complex multi-layer bugs spanning database, service, API, and UI
- Any bug where initial fix attempts have failed
- Situations requiring careful diagnosis before action
Workflow Overview
flowchart TD
START[User Reports Bug] --> CHECK{Architecture docs exist?}
CHECK -->|No| GEN[Generate architecture docs]
CHECK -->|Yes| READ[Read architecture docs]
GEN --> READ
READ --> CONTEXT[Gather bug context]
CONTEXT --> LOGS[Add diagnostic logs/instrumentation]
LOGS --> REPRODUCE[Attempt to reproduce bug]
REPRODUCE --> ANALYZE[Analyze log output]
ANALYZE --> HYPOTHESIS[Generate 5-7 hypotheses]
HYPOTHESIS --> DISTILL[Distill to 1-2 most likely causes]
DISTILL --> VALIDATE[Validate with diagnostic data]
VALIDATE --> PRESENT[Present diagnosis to user]
PRESENT --> CONFIRM{User confirms diagnosis?}
CONFIRM -->|No| LOGS
CONFIRM -->|Yes| FIX[Implement fix]
FIX --> TEST[Test fix thoroughly]
TEST --> VERIFY[Verify bug resolved]
VERIFY --> CLEANUP[Remove diagnostic logs]
CLEANUP --> DOCS[Document root cause]
DOCS --> COMPLETE[Bug Fixed]
style START fill:#fbb,stroke:#333,stroke-width:2px
style COMPLETE fill:#bfb,stroke:#333,stroke-width:2px
style CONFIRM fill:#ffb,stroke:#333,stroke-width:2px
Phase Summary
| Phase | Name | Time | Description |
|---|---|---|---|
| 1 | Context Gathering | 5-10 min | Read architecture docs, gather bug context |
| 2 | Diagnostic Instrumentation | 10-15 min | Add targeted logging across affected layers |
| 3 | Reproduce & Analyze | 10-15 min | Reproduce bug, collect and analyze diagnostic data |
| 4 | Hypothesis Generation | 10-15 min | Generate 5-7 hypotheses, distill to 1-2 most likely |
| 5 | User Confirmation | MANDATORY | Present diagnosis, wait for explicit approval |
| 6 | Implement Fix | Variable | Fix code, add tests (ONLY after confirmation) |
| 7 | Testing & Verification | 10-15 min | Verify fix, run test suite, check for regressions |
| 8 | Documentation | 10 min | Document root cause and resolution |
See references/bugfix-phases.md for detailed phase instructions.
Key Principles
- Diagnostic-First: ALWAYS add instrumentation before attempting fixes
- Hypothesis-Driven: Generate multiple theories, validate with data
- User Confirmation: NEVER implement fix without explicit approval
- Architecture-Aware: Use architecture documentation for deep context
- Evidence-Based: All conclusions must be backed by diagnostic data
- Thorough Testing: Comprehensive tests for fix and edge cases
- Clean Cleanup: Remove ALL temporary diagnostic code after fix
Constraints
- STOP at Phase 5 and wait for user confirmation before implementing any fix
- Remove ALL diagnostic instrumentation after fix is verified
- Generate 5-7 hypotheses before distilling to most likely causes
- Document root cause and prevention strategy in resolution document
- Never guess - if diagnostic data is insufficient, add more instrumentation
Templates
references/templates/context.md- Bug context documentationreferences/templates/diagnostic-logs.md- Diagnostic log formatreferences/templates/diagnosis-report.md- Diagnosis presentation to userreferences/templates/resolution.md- Bug resolution documentation
Example
Bug Diagnosis: Null Pointer in User Service
Architecture Check:
- Read /docs/architecture/data-model.md
- Identified User entity and relationships
- Found service layer patterns
Phase 1: Adding Diagnostics
- Added 8 diagnostic log points
- Added error boundaries
- Added state tracking
Phase 2: Reproduction
- Bug reproduced (100% success rate)
- Diagnostic data collected
- Timeline: Error at T+45ms
Phase 3: Hypothesis Generation
Generated 5 hypotheses:
1. Missing eager loading (HIGH)
2. Null validation missing (MEDIUM)
3. Race condition (MEDIUM)
4. Cache issue (LOW)
5. Permission issue (LOW)
Distilled to:
PRIMARY: Missing eager loading (90% confidence)
SECONDARY: Null validation (10% confidence)
Diagnosis Report:
┌─────────────────────────────────────────┐
│ Root Cause: Missing Eager Loading │
│ │
│ User.subscription relationship not │
│ loaded by default. Service expects │
│ it to exist, causing undefined error. │
│ │
│ Fix: Add include: { subscription: true} │
│ to UserRepository.findById() │
└─────────────────────────────────────────┘
Does this diagnosis match your understanding?
[Waiting for user confirmation...]
User confirmed diagnosis
Implementing Fix:
- Updated UserRepository.findById()
- Added defensive null check
- Added relationship loading tests
- All tests passing (47/47)
Cleanup:
- Removed 8 diagnostic log points
- Restored original error handling
Documentation:
- Updated data-model.md with pattern
- Created resolution document
Bug Fixed!
Begin by gathering context about the reported bug and checking for architecture documentation.