Bug Reproduction & Fix
Reproduces a bug with a failing test first, isolates the root cause, then applies a minimal fix and confirms the test passes.
What this skill does
Key features
- Writes a failing test that reproduces the reported bug before fixing anything
- Isolates the root cause instead of patching symptoms
- Applies the smallest fix that turns the test green
- Confirms the previously failing test now passes
Use cases
- Turning a vague bug report into a concrete failing test
- Fixing a regression without introducing new ones
- Pinning down an intermittent failure to one root cause
SKILL.md
The skill definition — its metadata and the exact instructions an agent follows. Copy it into a SKILL.md file in your agent's skills folder.
| 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 |
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>)FAQ
Why write a test before fixing?
A failing test proves the bug exists and proves the fix works. Without it you are guessing. The test also guards against the same regression returning later.
Does it make large changes to fix a bug?
No. It targets the single root cause with the smallest change that turns the test green. No shotgun edits, no unrelated refactoring bundled into the fix.
Before running any skill, read its instructions and the tools it's allowed to use, and test it on a safe target first. See LLM security best practices.