Reproduce-First Bug Fix: Failing Test, Minimal Patch, and Regression Proof

Directs Claude Code to reproduce a reported bug with a failing test, apply the smallest fix, and prove the fix with command output. Use it to decide whether a bug is fixed and safe to merge.

You get: Job-to-be-done and merge decision supported, root cause and hypotheses table

More like this

The prompt

reproduce-first-bug-fix-failing-test-minimal-patch-and-regression-proof.md
Role: You are a careful debugging engineer working in Claude Code with permission to edit files and run tests in {repo_path}.

Context: A bug has been reported and I must decide whether the fix is correct, minimal, and safe to merge. Do not refactor unrelated code.

Task: Reproduce the bug, write a failing test that captures it, implement the smallest fix that makes the test pass, and confirm nothing else regressed.

Inputs:
- Bug report (symptoms, steps, expected vs actual): {bug_report}
- Repo path: {repo_path}
- Test command: {test_command}
- Suspected area, if any: {suspected_area}
- Environment notes (versions, flags, OS): {environment}

Constraints:
- Work on a new branch named fix/{short_slug}. Do not push or force-push.
- Write the failing test BEFORE changing production code and run it to show it fails for the stated reason.
- Change as few lines as possible. No drive-by formatting, renames, or dependency changes.
- Never claim a command passed unless you ran it and saw the output in this session. If you cannot run something, say so.
- Keep assumptions separate from verified facts. If the bug cannot be reproduced after 3 distinct attempts, stop and report what you tried.

Workflow:
1. Read the bug report and restate expected vs actual behavior.
2. Locate the relevant code and existing tests using search tools.
3. Reproduce with a script or test; capture the failing output.
4. Form up to 3 root-cause hypotheses and test them with evidence, ruling them in or out.
5. Write the failing regression test, run it, confirm failure.
6. Implement the minimal fix, run the new test, then the full relevant suite plus lint and type checks if configured.
7. Review git diff for anything unrelated and revert it.

Output format:
1. Job-to-be-done and merge decision supported
2. Root cause (verified evidence with file:line)
3. Hypotheses table (hypothesis | evidence | verdict)
4. Changes made (table: file | change | reason)
5. Verification log (command | result summary), with the failing-then-passing test shown
6. Assumptions and missing information
7. Risks and edge cases not covered
8. Next actions (follow-ups, docs, release notes)

Acceptance criteria:
- A new test fails before the fix and passes after, with both runs reported.
- The diff touches only files necessary for the fix and test.
- The full relevant test suite and lint results are reported honestly, including failures that predate the change.
- The root cause is explained, not just the symptom patched.

Quality checks:
- Run git diff --stat and justify every file listed.
- Confirm the regression test would fail if the fix were reverted.
- Check for the same bug pattern elsewhere with a search and list hits without fixing them.
- Confirm no secrets, debug prints, or skipped tests were left behind.

Tips and common edits

Works best when the bug report includes exact error text and steps. Use a clean working tree so the diff review is meaningful. If tests need services such as a database, list that in the environment variable.

Questions about this prompt

Claude Code Root-Cause Bug Investigation with Failing Test and Minimal Patch

Directs Claude Code to reproduce a bug, trace it to a root cause using repository evidence, write a failing regression test, and apply the smallest safe fix. Ends with a verified diff, risks, and next actions.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Agent Session Handoff Brief with Resume Checklist and Verified State

Makes Claude Code produce a handoff file capturing goal, verified repo state, decisions, blockers, and exact resume commands so another engineer or agent session can continue without rework. Use it before ending a long task.

Characterization-Test-Backed Refactor with Incremental Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then making small, reversible commits. Helps you decide whether the refactor preserved behavior and is worth merging.

Claude Code Repo Recon and Implementation Plan for a New Feature

Has Claude Code inspect a repository read-only and produce an evidence-based implementation plan with file-level changes, tests, risks, and open questions. Use it to decide whether to start, split, or clarify a feature before any code is written.

Pre-Merge Self-Review of a Git Diff: Correctness, Security, and Test Gaps

Has Claude Code review a branch diff like a skeptical maintainer, producing severity-ranked findings with evidence and a clear merge, fix, or block recommendation. Use it before opening or approving a pull request.

Cursor Agent Bug Triage: Reproduce, Root-Cause, Fix, and Regression Test

Guides Cursor Agent through reproducing a bug, isolating the root cause with evidence, applying a minimal diff, and adding a regression test, ending with a verification checklist and risks.

Claude Code Feature Implementation Plan and Build from a Ticket with Repo Convention Discovery

Has Claude Code investigate how similar features are built in the repository, produce an implementation plan with acceptance tests, then implement it in verified increments. Surfaces risks, open questions, and next actions before and after coding.

Debug an Error From the Message and the Code Around It

Finds the most likely cause of an error from the message and the relevant code, ranks other possible causes, and gives the smallest fix plus a way to prove it worked.

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.