bugfix

name	bugfix
description	Systematic bug investigation and fix workflow. Gathers symptoms, forms hypotheses, investigates root cause, implements fix, and verifies. Use for debugging, fixing errors, or troubleshooting. Triggers: debug, fix bug, troubleshoot, why is this broken.

User request: $ARGUMENTS

Systematic bug investigation and fix workflow. Follows: Understand → Hypothesize → Investigate → Fix → Verify.

Investigation log: /tmp/bugfix-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - external memory for findings.

Phase 1: Understand the Bug

1.1 Create Todo List

- [ ] Gather bug symptoms and context
- [ ] Form initial hypotheses
- [ ] (expand as investigation reveals new areas)
- [ ] Implement and verify fix

1.2 Create Investigation Log

Path: /tmp/bugfix-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

# Bug Investigation: {description}
Started: {timestamp}

## Symptoms
(populated below)

## Hypotheses
(populated in Phase 2)

## Investigation Log
(populated during investigation)

## Root Cause
(populated when identified)

## Fix Applied
(populated after fix)

1.3 Gather Symptoms

If $ARGUMENTS contains sufficient context (error message, steps to reproduce, expected vs actual behavior), extract and document in log.

Otherwise, ask user for missing information:

Bug Report Details Needed

To investigate effectively, please provide:

1. **What happened?** (Error message, unexpected behavior)
2. **What did you expect?** (Expected behavior)
3. **Steps to reproduce** (If known)
4. **When did it start?** (Recent change, always broken, intermittent)
5. **Environment** (Browser, OS, versions - if relevant)

Provide what you know - I can investigate the rest.

Document all symptoms in investigation log immediately.

1.4 Locate Relevant Code

Search codebase for:

• Files mentioned in error messages
• Functions/components referenced
• Recent changes (if "started after X" was mentioned)
• Related test files

Update log with located files.

Phase 2: Form Hypotheses

2.1 Generate Hypotheses

Based on symptoms and located code, form 2-4 hypotheses ranked by likelihood:

## Hypotheses

### H1: [Most likely] {Description}
- Evidence for: {what supports this}
- Evidence against: {what contradicts}
- Test: {how to verify/falsify}

### H2: {Description}
- Evidence for: {what supports}
- Evidence against: {what contradicts}
- Test: {how to verify/falsify}

### H3: [Least likely] {Description}
...

2.2 Update Todos

- [x] Gather bug symptoms and context
- [ ] Form initial hypotheses
- [ ] Investigate H1: {description}
- [ ] Investigate H2: {description}
- [ ] (expand as investigation reveals new areas)
- [ ] Implement and verify fix

Phase 3: Investigate

Investigation Loop

For each hypothesis (in likelihood order):

1. Mark todo in_progress
2. Read relevant code files fully
3. Trace execution paths
4. Look for conditions that match symptoms
5. Write findings immediately to investigation log
6. Update hypothesis status: CONFIRMED | REFUTED | NEEDS MORE DATA
7. If confirmed → proceed to Phase 4
8. If refuted → mark completed, investigate next hypothesis
9. If all refuted → expand hypotheses based on new learnings

3.1 Investigation Techniques

Symptom Type	Investigation Approach
Error thrown	Read stack trace, trace to origin, check error handlers
Wrong output	Trace data flow, check transformations, validate inputs
Performance	Profile execution, check loops/recursion, memory patterns
Race condition	Check async operations, state mutations, timing
Intermittent	Look for external dependencies, caching, timing

General techniques:

• Read error messages and stack traces carefully
• Check logs and debugging output
• Examine data flow and state changes
• Consider environmental factors (OS, versions, config)
• Review recent commits for related changes (git log --oneline -20)

3.2 Log Format

After each investigation step:

### {timestamp} - Investigating H{N}
**Files examined**: {list}
**Findings**: {what discovered}
**Status**: CONFIRMED | REFUTED | NEEDS MORE DATA
**Next**: {what to check next or "proceed to fix"}

3.3 Root Cause Identified

When root cause is found:

## Root Cause

**Hypothesis confirmed**: H{N}
**Location**: {file}:{line}
**Cause**: {clear explanation}
**Evidence**: {code showing the bug}

If no hypothesis was confirmed but investigation revealed the actual cause, document the unexpected finding and proceed.

Phase 4: Test-First (When Applicable)

Before fixing, create a test that reproduces the bug when practical:

4.1 Create Reproducing Test

- Find the most appropriate existing test file for the component
- Create a minimal, focused test that reproduces the bug
- Run the test to verify it fails as expected
- If test passes, refine until it properly reproduces the issue

Why test-first?

• Proves you understand the bug
• Provides automatic verification when fix is applied
• Prevents regression in the future
• Documents the bug behavior

Skip test-first when:

• Bug is in UI/visual layer without existing test infrastructure
• Environment-specific issue that can't be unit tested
• Urgent hotfix where manual verification is sufficient (note in log)

4.2 Document Test in Log

## Reproducing Test

**Test file**: {path}
**Test name**: {description}
**Status**: FAILS AS EXPECTED | SKIPPED (reason)

Phase 5: Fix

5.1 Plan the Fix

Before implementing, document:

## Planned Fix

**Approach**: {what will change}
**Files to modify**: {list}
**Risk assessment**: {potential side effects}
**Test strategy**: {how to verify}

5.2 Implement Fix

Apply the minimal fix:

• Change only what's necessary
• Follow existing code patterns
• Don't refactor unrelated code
• Add comments if the fix isn't obvious

5.3 Run Quality Gates

# TypeScript: tsc --noEmit
# Tests: npm test (or project-specific)
# Lint: npm run lint (or project-specific)

5.4 Handle Gate Failures

If gates fail after fix:

1. Analyze if failure is related to fix or pre-existing
2. If related: adjust fix, re-run gates (max 5 attempts)
3. If pre-existing: note in log, continue
4. If stuck after 5 attempts: escalate with findings

Phase 6: Verify

6.1 Run Reproducing Test

If test was created in Phase 4:

• Run the test that previously failed
• If it passes → fix is verified
• If it still fails → return to Phase 5 to adjust fix

Attempt to reproduce the original bug:

• If bug no longer reproduces → fix likely successful
• If bug still reproduces → fix incomplete, return to Phase 3

6.2 Manual Verification

If no reproducing test exists:

• Attempt to reproduce the original bug
• If bug no longer reproduces → fix likely successful
• If bug still reproduces → fix incomplete, return to Phase 3

6.3 Check for Regression

Verify the fix didn't break related functionality:

• Run related tests
• Check adjacent code paths
• Consider edge cases

6.4 Document Fix

Update investigation log:

## Fix Applied

**Files modified**: {list with changes}
**Verification**: {how verified}
**Gates**: PASS | FAIL (reason)

## Summary

**Bug**: {description}
**Root cause**: {explanation}
**Fix**: {what was changed}
**Status**: FIXED | PARTIALLY FIXED | ESCALATED

6.5 Report to User

## Bug Fix Complete

**Bug**: {description}
**Root cause**: {one sentence}
**Fix**: {what was changed}
**Files modified**: {list}
**Verification**: All gates pass, bug no longer reproduces

**Investigation log**: /tmp/bugfix-{...}.md

Edge Cases

Case	Action
Cannot reproduce bug	Ask user for more details, check environment differences
All hypotheses refuted	Form new hypotheses based on learnings, expand investigation
Fix would require major refactor	Document scope, escalate to user for decision
Multiple bugs discovered	Focus on reported bug, note others in log for later
Bug is in third-party code	Document workaround options, escalate
Intermittent bug	Add logging/instrumentation to gather more data

Principles

• Write findings immediately — investigation log is external memory
• Test-first when possible — a reproducing test proves understanding
• One bug at a time — don't fix unrelated issues
• Minimal fix — change only what's necessary
• Verify thoroughly — ensure fix works and doesn't regress
• Escalate when stuck — don't spin indefinitely

Quality Standards

• Tests must be deterministic and reliable
• Fixes should be clean and maintainable
• No introduction of new bugs or regressions
• Clear comments explaining non-obvious fixes
• Follow project coding standards and patterns