Fix Bug

---
name: fix-bug
description: Fix a bug using test-driven development. Use when the user reports a bug, describes unexpected behavior, wants to fix a defect, or says something is broken. Enforces a strict test-first workflow where a failing test must be written and verified before any fix is attempted.
argument-hint: "[bug description]"
allowed-tools: Read, Grep, Glob, Edit, Write, Bash
---
<!-- agent-pmo:74cf183 -->

# Bug Fix Skill — Test-First Workflow

You MUST follow this exact workflow. Do NOT skip steps. Do NOT fix the bug before writing a failing test.

## Step 1: Understand the Bug

- Read the bug description: $ARGUMENTS
- Investigate the codebase to understand the relevant code
- Identify the root cause (or narrow down candidates)
- Summarize your understanding of the bug to the user before proceeding

## Step 2: Write a Failing Test

- Write a test that **directly exercises the buggy behavior**
- The test must assert the **correct/expected** behavior — so it FAILS against the current broken code
- The test name should clearly describe the bug (e.g., `test_orange_color_not_applied_to_head`)
- Use the project's existing test framework and conventions

## Step 3: Run the Test — Confirm It FAILS

- Run ONLY the new test (not the full suite)
- **Verify the test FAILS** and that it fails **because of the bug**, not for some other reason (typo, import error, wrong selector, etc.)
- If the test passes: your test does not capture the bug. Go back to Step 2
- If the test fails for the wrong reason: fix the test, not the code. Go back to Step 2
- **Repeat until the test fails specifically because of the bug**

## Step 4: Show Failure to User

- Show the user the test code and the failure output
- Explicitly ask: "This test fails because of the bug. Can you confirm this captures the issue before I fix it?"
- **STOP and WAIT for user acknowledgment before proceeding**
- Do NOT continue to Step 5 until the user confirms

## Step 5: Fix the Bug

- Make the **minimum change** needed to fix the bug
- Do not refactor, clean up, or "improve" surrounding code
- Do not change the test

## Step 6: Run the Test — Confirm It PASSES

- Run the new test again
- **Verify it PASSES**
- If it fails: go back to Step 5 and adjust the fix
- **Repeat until the test passes**

## Step 7: Run the Full Test Suite

- Run ALL tests to make sure nothing else broke
- If other tests fail: fix the regression without breaking the new test
- Report the final result to the user

## Rules

- NEVER fix the bug before the failing test is written and confirmed
- NEVER skip asking the user to acknowledge the test failure
- NEVER modify the test to make it pass — modify the source code
- If you cannot write a test for the bug, explain why and ask the user how to proceed
- Keep the fix minimal — one bug, one fix, one test