| name | debug-a-bug |
| category | code |
| description | Reproduce a software defect, isolate its smallest proven cause, implement a narrow fix, and verify both the failure and surrounding behavior. Use when someone says "fix this bug," reports a regression, or has an error that needs diagnosis and repair. |
debug-a-bug
Turn a report into a repeatable failing case, then make the smallest change that explains why
the failure disappears. Preserve the evidence that separates a verified fix from a plausible guess.
When to use
Use this for incorrect behavior in an existing codebase when implementation is in scope. If the
request is diagnosis only, stop after the causal explanation and evidence. For a live outage,
contain user impact with debug-a-production-incident before editing code.
Inputs
- Read the repository instructions, current worktree state, relevant code, and existing tests.
- Capture the observed result, expected result, environment, inputs, and last known working state.
- Separate facts from reporter assumptions. Preserve unrelated local changes.
Procedure
- Reproduce the symptom with the smallest command, request, fixture, or interaction that still fails.
Record exact output and environment details. If it cannot be reproduced, gather more evidence rather
than changing code speculatively.
- Reduce the search area using the execution path, logs, recent changes, and controlled comparisons.
Change one variable at a time.
- Write or identify a regression check that fails for the reported reason. Avoid a test that merely
restates the current implementation.
- Trace the failing value or state backward to the first point where it becomes wrong. Name the
invariant violated there and the evidence supporting that conclusion.
- Consider at least one competing explanation. Use a targeted observation or experiment to reject it.
- Implement the smallest fix at the broken boundary. Do not mix refactoring, formatting, dependency
upgrades, or unrelated cleanup into the repair.
- Run the regression check and the narrow surrounding test set. Then run the repository's required
broader checks in proportion to the change's risk.
- Test nearby boundaries such as empty input, repeated execution, error paths, and the last known
working case. Confirm the fix does not only handle the reporter's exact example.
- Review the diff for accidental changes, debug output, weakened assertions, exposed data, and
environment-specific assumptions.
- Write a short repair record: symptom, root cause, fix, tests run, and any residual risk or follow-up.
Boundaries
Do not claim a root cause unless the evidence connects it to the symptom. Do not delete user data,
reset a worktree, weaken security checks, or expose private production records to make reproduction
easier. Ask before changing public behavior beyond the reported defect.
Done
- A saved regression check fails before the fix and passes after it for the expected reason
- The repair record identifies the broken invariant and links it to observed evidence
- Targeted and required broader tests pass, with commands and results recorded
- The final diff contains only the fix, its proof, and explicitly approved supporting changes
Then use review-a-pull-request for an independent change review.
