fix-bug

What this skill does

# Bug Fix

Fix bugs systematically using test-driven development, root cause analysis, and comprehensive verification across any project type.

## Anti-Hallucination Guidelines

**CRITICAL**: Bug fixes must be based on ACTUAL code and VERIFIED test results:
1. **Reproduce the bug first** - Do not fix what has not been seen failing. Run the failing test or scenario to confirm the bug exists.
2. **Test-driven approach** - Write/locate a failing test before implementing the fix. Verify it actually fails.
3. **Verify root cause** - Use grep/search to locate actual bug location with evidence (file paths, line numbers).
4. **Test verification** - Run full test suite to prove fix works. All tests must pass.
5. **No invented fixes** - Only implement solutions that address the demonstrated root cause.
6. **Reference real code** - Never make claims about code that has not been read.

## Quality Gates

This skill includes automatic bug fix verification before completion:

### Fix Verification (Stop Hook)

When you attempt to stop working (mark bug as fixed), an automated verification agent runs to ensure the fix is complete:

**Verification Steps:**
1. **Fix Confirmation**: Runs the originally failing test or reproduces the bug scenario. Must now pass/work.
2. **Regression Check**: Runs full test suite to ensure no new bugs introduced
3. **Root Cause Validation**: Verifies the fix addresses the actual root cause, not just symptoms

**Behavior:**
- ✅ **All verifications pass**: Bug marked as fixed
- ❌ **Any verification fails**: Completion blocked, Claude continues debugging
- ⚠️ **Original test not identified**: Hook attempts to find relevant tests or asks for clarification

**Example blocked completion:**
```
⚠️ Bug fix verification failed:

Original Issue: ❌ STILL FAILING
  - The bug still reproduces with the same error
  - Test: test_user_login still fails with AuthenticationError

Regression: ✅ PASSED (other tests still pass)

🔧 The fix does not resolve the original issue. Root cause analysis needed.
```

**Benefits:**
- Prevents marking bugs "fixed" when they still reproduce
- Catches regression bugs introduced by the fix
- Enforces test-driven debugging discipline
- Ensures actual root cause is addressed, not just symptoms

## Bug Description

$ARGUMENTS

## Task Management

This skill uses Claude Code's Task Management System for strict sequential dependency tracking through the debugging workflow.

**When to Use Tasks:**
- Multi-step debugging requiring root cause analysis
- Bugs spanning multiple files or components
- Work requiring progress tracking across sessions

**When to Skip Tasks:**
- Trivial 1-line fixes with obvious solutions
- Simple typo corrections
- Quick configuration changes

**Task Structure:**
Bug fixes create a strict sequential chain where each phase must complete before the next can start, ensuring test-driven development discipline.

## Implementation Workflow

**Task tracking replaces TodoWrite.** Create task chain at start, update as completing each phase.

### Phase 0: Project Discovery (REQUIRED)

**Step 0.1: Create Task Dependency Chain**

Before debugging, create the strict sequential task structure:

```
TaskCreate:
  subject: "Phase 0: Discover project workflow"
  description: "Identify test, lint, debug commands from CLAUDE.md and task runners"
  activeForm: "Discovering project workflow"

TaskCreate:
  subject: "Phase 1: Reproduce and analyze bug"
  description: "Locate failing test, reproduce bug, identify root cause"
  activeForm: "Analyzing bug"

TaskCreate:
  subject: "Phase 2: Plan fix"
  description: "Design minimal fix approach"
  activeForm: "Planning fix"

TaskCreate:
  subject: "Phase 3: Implement fix"
  description: "Apply fix and verify test passes"
  activeForm: "Implementing fix"

TaskCreate:
  subject: "Phase 4: Verify quality"
  description: "Run full test suite, lint, type-check"
  activeForm: "Verifying fix quality"

TaskCreate:
  subject: "Phase 5: Final commit"
  description: "Create conventional commit with fix details"
  activeForm: "Creating final commit"

# Set up strict sequential chain
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }
TaskUpdate: { taskId: "3", addBlockedBy: ["2"] }
TaskUpdate: { taskId: "4", addBlockedBy: ["3"] }
TaskUpdate: { taskId: "5", addBlockedBy: ["4"] }
TaskUpdate: { taskId: "6", addBlockedBy: ["5"] }

# Start first task
TaskUpdate: { taskId: "1", status: "in_progress" }
```

**Step 0.2: Discover Project Workflow**

Use Haiku-powered Explore agent for token-efficient discovery:

```
Use Task tool with Explore agent:
- prompt: "Discover the development workflow for this project:
    1. Read CLAUDE.md if it exists - extract debugging and testing conventions
    2. Check for task runners: Makefile, justfile, package.json scripts, pyproject.toml scripts
    3. Identify the test command (e.g., make test, just test, npm test, pytest, bun test)
    4. Identify how to run a single test or test file
    5. Identify the lint command (e.g., make lint, npm run lint, ruff check)
    6. Identify the type-check command if applicable
    7. Identify the dev server command if this is a web app
    8. Check for debugging tools (pytest -v, npm run test:debug, etc.)
    9. Note any pre-commit hooks or quality gates
    Return a structured summary of all available commands."
- subagent_type: "Explore"
- model: "haiku"  # Token-efficient for discovery
```

Store discovered commands for use in later phases.

**IMPORTANT**: Never assume which test framework or tools are available. Use only the discovered commands.

**Step 0.3: Complete Phase 0**

```
TaskUpdate: { taskId: "1", status: "completed" }
TaskList  # Check that Task 2 is now unblocked
```

### Phase 1: Bug Analysis & Reproduction

**Goal**: Understand the bug, locate it in code, and reproduce it reliably.

**Step 1.0: Start Phase 1**

```
TaskUpdate: { taskId: "2", status: "in_progress" }
```

**Step 1.1: Understand Bug Symptoms**

If the user provided an issue ID or bug description:
- Read the issue/ticket if accessible (use Bash with `gh issue view` or `jira issue view` if available)
- Understand expected vs actual behavior
- Identify error messages or symptoms

If the user did not provide clear symptoms, use `AskUserQuestion` to clarify expected behavior, actual behavior, reproduction steps, and whether an existing failing test exists.

**Step 1.2: Locate or Create Failing Test**

Search for existing test coverage using Grep. If no test exists for this bug:
- Create a minimal failing test that reproduces the bug
- Place it in appropriate test file following project conventions
- Use discovered test patterns from existing tests

**Step 1.3: Reproduce the Bug**

Run the specific test using discovered test command. **CRITICAL**: Verify the test actually fails. Capture error output.

**Step 1.4: Root Cause Analysis**

Use parallel subagents for comprehensive analysis with Haiku for exploration:

```
Agent 1 - Bug Location (Explore, Haiku):
  prompt: "Find the exact location of the bug (file path, line numbers),
          read the buggy code and surrounding context,
          identify why the code produces the wrong behavior,
          provide evidence (stack trace, variable values, control flow)."
  subagent_type: "Explore"
  model: "haiku"  # Token-efficient for code exploration

Agent 2 - Impact Analysis (Explore, Haiku):
  prompt: "Search the codebase for other code affected by the same issue,
          similar patterns with the same bug, related tests that might fail,
          dependencies or callers of the buggy code."
  subagent_type: "Explore"
  model: "haiku"  # Token-efficient for codebase search

Agent 3 - Research (general-purpose, Haiku, only if external library involved):
  prompt: "Search for documented solutions or patterns for this type of bug
          in [LIBRARY_NAME] library using Context7 and web search."
  subagent_type: "general-purpose"
  model: "haiku"  # Token-efficient for research
```

**Step 1.5: Confi