thoreinstein/bugfix

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

1. Diagnostic-First: ALWAYS add instrumentation before attempting fixes
2. Hypothesis-Driven: Generate multiple theories, validate with data
3. User Confirmation: NEVER implement fix without explicit approval
4. Architecture-Aware: Use architecture documentation for deep context
5. Evidence-Based: All conclusions must be backed by diagnostic data
6. Thorough Testing: Comprehensive tests for fix and edge cases
7. 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 documentation
• references/templates/diagnostic-logs.md - Diagnostic log format
• references/templates/diagnosis-report.md - Diagnosis presentation to user
• references/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.