---
name: bug-fix
description: "Reproduce a bug with a failing test, find the root cause, and apply a minimal verified fix."
allowed-tools: ["Read", "Grep", "Edit", "Bash(pytest:*)", "Bash(npm test:*)", "Bash(git diff:*)"]
output: "failing test + minimal fix"
order: "reproduce before fix"
---

# Bug Reproduction & Fix

## Musts

- Reproduce the bug FIRST with a new test that fails for the reported reason; do not touch source until you have a red test.
- Isolate the root cause and state it in one sentence before proposing a fix — trace the actual failing path, do not guess.
- Apply the minimal fix that addresses the root cause; do not fix unrelated issues in the same change.
- Run the new test plus the surrounding suite and confirm the target test now passes and nothing else broke.
- If you cannot reproduce the bug, say so and report exactly what you tried rather than inventing a fix.

## Guidelines

- Put the failing test where the project keeps tests, mirroring existing naming and structure.
- Prefer a test that asserts on observable behavior over one coupled to internal implementation.
- If the root cause is a design flaw, fix the immediate bug minimally and flag the deeper issue separately.
- Propose the diff for human approval; note any risk the fix carries.

## Output format

```
## Reproduction
test: <path> — asserts <expected> vs actual <observed>
status before fix: FAIL

## Root cause
<one sentence, with file:line>

## Fix
<unified diff, minimal>

## Verification
target test: PASS
surrounding suite: <pass/fail> (<command run>)
```