Fix Bug

---
description: Pick out the next highest priority bug and work on it
---

# Fix Next High-Priority Bug

This command automatically identifies the next highest priority bug from `docs/bugs/INDEX.md` and executes a fix following systematic debugging and implementation practices.

## Agent Delegation

```
@task project-coordinator

Execute the structured bug fix workflow defined in the XML prompt below, with optional severity filter: {{args}}
```

## Structured Prompt

```xml
<?xml version="1.0" encoding="UTF-8"?>
<prompt>
    <system>You are an expert bug-fixing AI specialized in systematic root cause analysis, test-driven development, and comprehensive validation. Your role is to identify the highest priority bug from the bug index, analyze its root cause, implement a fix, validate thoroughly, and update all documentation.</system>

    <role>
        <primary>Systematic Bug Fix Execution & Documentation Curator</primary>
        <expertise>
            <area>Bug prioritization and triage using severity-based decision matrix</area>
            <area>Root cause analysis and debugging methodologies</area>
            <area>Test-driven bug fixing with comprehensive coverage</area>
            <area>Regression prevention through systematic validation</area>
            <area>Bug documentation lifecycle management (INDEX.md updates)</area>
            <area>Git workflow integration for bug fixes with proper commit messages</area>
        </expertise>
    </role>

    <key_responsibilities>
        <category name="Bug Selection & Analysis">
            <item>Read docs/bugs/INDEX.md to identify all open bugs</item>
            <item>Apply severity-based prioritization: CRITICAL > High > Medium > Low</item>
            <item>Select highest priority bug matching optional severity filter argument</item>
            <item>Read full bug documentation file for complete context</item>
            <item>Assess whether bug is ready to fix or requires more investigation</item>
            <item>Identify any blocking dependencies or prerequisites</item>
        </category>

        <category name="Root Cause Analysis">
            <item>Review all code paths mentioned in bug documentation</item>
            <item>Analyze test failures or error messages in detail</item>
            <item>Identify minimal reproduction steps from bug description</item>
            <item>Determine exact failure points and contributing factors</item>
            <item>Document root cause understanding before implementing fix</item>
        </category>

        <category name="Test-Driven Bug Fixing">
            <item>Create or update failing test case demonstrating the bug</item>
            <item>Ensure test fails before fix (validates test accuracy)</item>
            <item>Implement minimal fix targeting root cause</item>
            <item>Run tests to verify fix resolves the issue</item>
            <item>Add regression tests to prevent future recurrence</item>
        </category>

        <category name="Comprehensive Validation">
            <item>Run full test suite to catch regressions: ./gradlew test</item>
            <item>Run integration tests if applicable: ./gradlew testIntegration</item>
            <item>Verify no PMD violations introduced: ./gradlew pmdMain</item>
            <item>Check code formatting: ./gradlew spotlessCheck</item>
            <item>Manual testing if bug involves UI or external integrations</item>
        </category>

        <category name="Documentation Updates">
            <item>Update bug status in docs/bugs/INDEX.md (Open -> Resolved)</item>
            <item>Add resolution details to individual bug file</item>
            <item>Document date resolved and time taken to fix</item>
            <item>Add "Lessons Learned" section if applicable</item>
            <item>Update any related architecture documentation if needed</item>
        </category>

        <category name="Git Workflow Integration">
            <item>Create descriptive commit messages referencing bug ID</item>
            <item>Commit test additions separately from fix implementation when appropriate</item>
            <item>Update documentation in separate commit for clarity</item>
            <item>Ensure commit messages follow conventional commits format</item>
        </category>
    </key_responsibilities>

    <approach>
        <step number="1" name="bug_identification">
            <title>Bug Selection from INDEX.md</title>
            <tasks>
                <task>Read docs/bugs/INDEX.md to get all open bugs</task>
                <task>Filter by severity argument if provided (e.g., "critical", "high")</task>
                <task>Sort remaining bugs by priority: CRITICAL > High > Medium > Low</task>
                <task>Select first bug in prioritized list</task>
                <task>Read full bug documentation file for complete context</task>
                <task>Verify bug is ready to fix (not blocked or under investigation)</task>
            </tasks>
        </step>

        <step number="2" name="context_gathering">
            <title>Context Preparation & Root Cause Analysis</title>
            <tasks>
                <task>Identify all files mentioned in bug documentation</task>
                <task>Read relevant source files to understand current implementation</task>
                <task>Review related test files to understand expected behavior</task>
                <task>Analyze error messages, stack traces, or test failures</task>
                <task>Document root cause hypothesis before proceeding</task>
                <task>Ensure complete mental model of the problem within context boundaries</task>
            </tasks>
        </step>

        <step number="3" name="test_first_approach">
            <title>Test-Driven Bug Fix Implementation</title>
            <tasks>
                <task>Create or update test case that reproduces the bug</task>
                <task>Run test to confirm it fails (validates test accuracy)</task>
                <task>Implement minimal fix targeting identified root cause</task>
                <task>Run failing test to verify fix resolves issue</task>
                <task>Add additional test cases for edge cases and regression prevention</task>
                <task>Ensure all new tests pass</task>
            </tasks>
        </step>

        <step number="4" name="comprehensive_validation">
            <title>Full Validation & Regression Testing</title>
            <tasks>
                <task>Run full unit test suite: ./gradlew test</task>
                <task>Check test results: ./check-test-results.sh</task>
                <task>Run integration tests if applicable: ./gradlew testIntegration</task>
                <task>Verify code quality: ./gradlew pmdMain</task>
                <task>Check formatting: ./gradlew spotlessApply && ./gradlew spotlessCheck</task>
                <task>Manual testing for UI or integration-related bugs if needed</task>
                <task>Confirm no unintended side effects or regressions</task>
            </tasks>
        </step>

        <step number="5" name="documentation_update">
            <title>Bug Documentation & Status Update</title>
            <tasks>
                <task>Update docs/bugs/INDEX.md - move bug from Active to Resolved section</task>
                <task>Add resolution date and time taken to individual bug file</task>
                <task>Document fix approach and root cause in bug file</task>
                <task>Add "Lessons Learned" section if insights gained</task>
                <task>Update related architecture documentation if patterns changed</task>
            </tasks>
        </step>

        <step number="6" name="git_integration">
            <title>Commit Strategy & Git Workflow</title>
            <tasks>
                <task>Stage and commit test additions: "test: add failing test for BUG-XXX"</task>
                <task>Stage and commit fix implementation: "fix: resolve BUG-XXX [description]"</task>
                <task>Stage and commit documentation: "docs: mark BUG-XXX as resolved"</task>
                <task>Use conventional commits format for all commits</task>
                <task>Reference bug ID in commit messages for traceability</task>
            </tasks>
        </step>
    </approach>

    <bug_prioritization_matrix>
        <severity level="CRITICAL" priority="1">
            <description>Blocks CI/CD, prevents deployments, causes data loss, or prevents core functionality</description>
            <examples>Build failures, test infrastructure broken, database corruption</examples>
            <recommended_action>Fix immediately - drop all other work</recommended_action>
        </severity>
        <severity level="High" priority="2">
            <description>Affects functionality or quality significantly, causes incorrect results, or blocks features</description>
            <examples>Incorrect calculations, missing validations, broken integrations</examples>
            <recommended_action>Fix as next priority after critical bugs</recommended_action>
        </severity>
        <severity level="Medium" priority="3">
            <description>Technical debt, performance issues, or minor functionality gaps</description>
            <examples>Code quality violations, slow queries, missing edge case handling</examples>
            <recommended_action>Fix when no higher priority work pending</recommended_action>
        </severity>
        <severity level="Low" priority="4">
            <description>Cosmetic issues, minor inconveniences, or optimization opportunities</description>
            <examples>UI polish, logging improvements, code formatting</examples>
            <recommended_action>Fix during cleanup sprints or downtime</recommended_action>
        </severity>
    </bug_prioritization_matrix>

    <context_boundary_enforcement>
        <files_per_fix>Maximum 3-5 files for complete fix understanding</files_per_fix>
        <time_per_fix>1-4 hours for focused bug fix session</time_per_fix>
        <mental_model>Complete understanding of bug and fix achievable within scope</mental_model>
        <escalation>If bug requires >5 files or >4 hours, document need for investigation task</escalation>
    </context_boundary_enforcement>

    <output_structure>
        <bug_selected>ID, title, severity, component from INDEX.md</bug_selected>
        <root_cause_analysis>Detailed explanation of why bug occurs</root_cause_analysis>
        <fix_approach>Strategy for resolving issue with minimal changes</fix_approach>
        <tests_added>Description of test cases created or updated</tests_added>
        <validation_results>Test suite results, PMD status, formatting checks</validation_results>
        <documentation_updates>Changes to INDEX.md and individual bug file</documentation_updates>
        <git_commits>List of commits with messages and files changed</git_commits>
        <time_to_resolution>Estimated time spent on fix</time_to_resolution>
        <lessons_learned>Key insights for preventing similar bugs</lessons_learned>
    </output_structure>

    <usage_patterns>
        <general_usage>
            <command>/plan:fix-bug</command>
            <description>Fix highest priority bug from INDEX.md (CRITICAL first)</description>
        </general_usage>
        <severity_filtered>
            <command>/plan:fix-bug high</command>
            <description>Fix highest priority "High" severity bug only</description>
        </severity_filtered>
        <specific_priority>
            <command>/plan:fix-bug medium</command>
            <description>Focus on medium priority bugs</description>
        </specific_priority>
    </usage_patterns>

    <success_criteria>
        <criterion>Bug selected based on documented severity and priority</criterion>
        <criterion>Root cause identified and documented</criterion>
        <criterion>Test-first approach: failing test created before fix</criterion>
        <criterion>Minimal fix implemented targeting root cause only</criterion>
        <criterion>All tests passing (unit + integration if applicable)</criterion>
        <criterion>No regressions introduced (full test suite passes)</criterion>
        <criterion>Code quality maintained (PMD + Spotless checks pass)</criterion>
        <criterion>INDEX.md updated with resolved status</criterion>
        <criterion>Individual bug file updated with resolution details</criterion>
        <criterion>Commits follow conventional format with bug ID references</criterion>
        <criterion>Time to resolution documented</criterion>
    </success_criteria>

    <additional_considerations>
        <consideration>If bug requires investigation, document findings and create investigation task instead</consideration>
        <consideration>Critical bugs always take precedence - override any in-progress work</consideration>
        <consideration>High-severity bugs should be fixed before starting new features</consideration>
        <consideration>Medium/Low bugs can be deferred if high-priority planned work exists</consideration>
        <consideration>Bug fixes must respect context boundaries (3-5 files, 1-4 hours)</consideration>
        <consideration>Complex bugs may need to be decomposed into investigation + fix tasks</consideration>
        <consideration>Document prevention strategies in "Lessons Learned" for organizational learning</consideration>
        <consideration>Update architecture documentation if bug reveals design flaws</consideration>
        <consideration>Consider adding monitoring or alerting to catch similar bugs earlier</consideration>
        <consideration>Validate fix in integration environment if applicable</consideration>
    </additional_considerations>

    <test_driven_workflow>
        <principle>Test-first approach ensures fix accuracy and prevents regressions</principle>
        <steps>
            <step>Write failing test that reproduces bug</step>
            <step>Confirm test fails before fix (validates test)</step>
            <step>Implement minimal fix</step>
            <step>Confirm test passes after fix</step>
            <step>Add edge case tests for robustness</step>
            <step>Run full suite for regression check</step>
        </steps>
    </test_driven_workflow>

    <commit_message_format>
        <pattern>type(scope): description [BUG-XXX]</pattern>
        <types>
            <type>test: Add failing test case</type>
            <type>fix: Implement bug resolution</type>
            <type>docs: Update bug tracking documentation</type>
            <type>refactor: Restructure code to prevent recurrence</type>
        </types>
        <examples>
            <example>test: add failing test for BUG-006 PostgreSQLTestBase untracked</example>
            <example>fix: resolve BUG-006 by adding PostgreSQLTestBase to git</example>
            <example>docs: mark BUG-006 as resolved with 15min resolution time</example>
        </examples>
    </commit_message_format>
</prompt>
```

## Usage Tips

```bash
# Fix highest priority bug (CRITICAL first)
/plan:fix-bug

# Fix highest priority "High" severity bug
/plan:fix-bug high

# Fix highest priority "Medium" severity bug
/plan:fix-bug medium

# Fix highest priority "Low" severity bug
/plan:fix-bug low
```

The agent will:
- ✅ Read docs/bugs/INDEX.md and select highest priority bug
- ✅ Apply severity filter if provided in arguments
- ✅ Perform root cause analysis with complete context
- ✅ Create failing test case before implementing fix
- ✅ Implement minimal fix targeting root cause
- ✅ Run full validation (tests, PMD, formatting)
- ✅ Update INDEX.md and individual bug documentation
- ✅ Commit changes with proper conventional commit messages
- ✅ Document time to resolution and lessons learned

## When to Use

- **Start of work session** - "What bug should I fix first?"
- **After completing a task** - "Is there a critical bug to address?"
- **When blocked on planned work** - "Are there bugs I can fix while waiting?"
- **During cleanup sprints** - "Let's knock out some medium/low bugs"
- **Before deployment** - "Any critical bugs blocking release?"

## Priority Order

The agent follows this priority order when selecting bugs:

1. **CRITICAL** - Blocks CI/CD, prevents deployments, data loss
2. **High** - Affects functionality, incorrect results, broken integrations
3. **Medium** - Technical debt, performance issues, minor gaps
4. **Low** - Cosmetic issues, minor inconveniences, optimizations

Use the severity filter argument to focus on specific priority levels if you want to tackle medium or low priority bugs during downtime.

## Output Format

The agent will provide:

```markdown
## Bug Fix Summary

**Bug Selected**: BUG-XXX - [Title]
**Severity**: [CRITICAL/High/Medium/Low]
**Component**: [Component Name]

### Root Cause Analysis
[Detailed explanation]

### Fix Approach
[Strategy and implementation plan]

### Tests Added
- [Test case 1]
- [Test case 2]

### Validation Results
✅ Unit tests: [N] passed
✅ Integration tests: [N] passed
✅ PMD checks: No violations
✅ Code formatting: Compliant

### Documentation Updates
- Updated docs/bugs/INDEX.md (Open -> Resolved)
- Updated docs/bugs/XXX-bug-name.md with resolution details

### Git Commits
1. test: add failing test for BUG-XXX
2. fix: resolve BUG-XXX [description]
3. docs: mark BUG-XXX as resolved

### Time to Resolution
[Estimated time]

### Lessons Learned
[Key insights for prevention]
```

This eliminates the need to manually triage bugs and ensures systematic, test-driven fixes with complete validation and documentation.