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.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Fix Bug?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/nimblesite-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