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

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 (Diffr uses mocha for unit and @vscode/test-electron for E2E — pick the right tier per CLAUDE.md)

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 make test to make sure nothing else broke (fail-fast + coverage threshold per CLAUDE.md)
• 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