bugfix

name	bugfix
description	Diagnose and fix bugs using hypothesis-driven debugging, diagnostic instrumentation, architecture-aware analysis, and evidence-based root cause identification

Bugfix

Agent Delegation

You MUST delegate complex root-cause analysis and debugging of unfamiliar patterns to the principal-engineer sub-agent. For deep codebase investigation, utilize the codebase_investigator. For unit test creation and verification of fix correctness, delegate to the sdet sub-agent.

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

Path Logic (Artifacts)

All artifacts produced during the bugfix process MUST be saved to the following location:

1. Identify Project Name: Use the BEADS_PROJECT_NAME env var or the current directory name.
2. Base Path: working/<project-name>/bugfix/<ticket-id>/

Artifact Paths:

• Context: <Base Path>/context.md
• Diagnostic Logs: <Base Path>/diagnostic-logs.md
• Diagnosis Report: <Base Path>/diagnosis-report.md
• Resolution: <Base Path>/resolution.md

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

• SMART BRANCHING — Before creating a branch, check the current environment.
  • Trunk Check: ONLY create a new branch if the current branch is a "trunk" branch (e.g., main, master).
  • Existing Branch: If already on a non-trunk branch (e.g., a feature branch or a branch with an open PR), continue working on the current branch.
  • Lineage Check: If on a trunk branch and a new branch is needed, check the ticket's lineage:
    • If this is a sub-task (child of a Story/Feature), check if a branch for the Parent Ticket already exists. If so, switch to it. If not, create the branch using the Parent Ticket's ID.
    • If this is a Feature/Story (child of Epic) or Standalone, create/use a branch for This Ticket.
  • Naming Convention: fix/<anchor-ticket-id>-<short-desc>
• MERGE IS USER-ONLY — A ticket status can only be changed to 'closed' AFTER the user informs the agent that the Pull Request has been merged into the trunk branch. The agent MUST NEVER merge their own PRs.
• PR CREATION — ONLY open a Pull Request if explicitly requested by the user.
• COMPOUND BEFORE CLOSE — The /compound skill MUST be run for every bugfix after merge and before marking the ticket as 'closed' in Beads.
• 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
• OBSIDIAN ARTIFACTS: All artifacts produced during the bugfix process MUST be saved to Obsidian using obsidian_create_note.
• LOCAL FILESYSTEM RESTRICTION: Do not use local filesystem write tools (write_file, etc.) for documentation or artifacts.

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

Phase 1: Context Gathering
- Read /docs/architecture/data-model.md
- Identified User entity and relationships
- Found service layer patterns

Phase 2: Diagnostic Instrumentation
- Added 8 diagnostic log points
- Added error boundaries
- Added state tracking

Phase 3: Reproduce & Analyze
- Bug reproduced (100% success rate)
- Diagnostic data collected
- Timeline: Error at T+45ms

Phase 4: 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.