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.