Bug Fix
Prove the causal defect, correct it at the owning boundary, and preserve the proof as a regression test.
Required Distinctions
| Term |
Meaning |
| Symptom |
The observed failure, with request/input/state and expected versus actual behavior |
| Root cause |
The earliest verified condition that explains the symptom |
| Fix |
The smallest change at the responsible boundary that removes the cause |
Do not label a symptom guard, rollback correlation, or plausible guess as root cause.
Investigate Before Editing
- Read applicable
AGENTS.md, complete errors/traces, related tests, recent changes, the narrow execution path, and any canonical requirement, architecture, README, or acceptance document that defines the expected behavior.
- Reproduce the symptom or create equivalent failing evidence. If intermittent or external, gather logs, metrics, or boundary observations instead of guessing.
- List competing hypotheses and the evidence that would distinguish them. Test one variable at a time, strongest evidence first.
- Trace bad state backward to its origin. Fix at the owning boundary; avoid a downstream null guard, broad catch, retry, or default value unless that is the verified contract.
Plan Gate
Before production edits, state:
- confirmed symptom and reproduction evidence;
- root-cause hypothesis and how it was verified;
- smallest proposed fix and exact area affected;
- compatibility, data, API, concurrency, security, and operational risks that apply;
- regression-test strategy and surrounding checks;
- documentation impact, including whether the defect reveals drift in requirements, architecture, usage instructions, or existing acceptance evidence;
- existing user changes to preserve;
- authorization boundary for local edits versus deploy, rollback, feature flag, canary, merge, or other external mutation.
Validate the plan for speculative edits, missed callers/layers, weakened semantics, unnecessary cleanup, and a smaller causal fix. Correct it before implementation.
When the fix depends on framework, library, SDK, database, or configuration behavior, determine the project version and use version-matching official documentation. If unavailable, require authoritative pinned artifacts plus executable evidence or keep the relevant claim unverified.
Implement and Verify
- Add the narrowest regression test or executable reproduction; confirm it fails for the observed defect.
- Implement only the causal correction. Do not weaken the test, change expected behavior to match the bug, swallow an exception, or bundle unrelated refactoring.
- Run the regression immediately, then relevant surrounding tests and available lint, type, build, integration, or configuration checks.
- Reproduce the original path again when feasible. Inspect Git status and diff; preserve pre-existing work and exclude unrelated edits.
- Map every plan item to exact changed files and fresh evidence.
- Synchronize only affected canonical documents. A narrow fix normally requires no new project documents; update an existing requirement, README, architecture map, or acceptance criterion only when the verified fix or confirmed contract changes its content. Never mark the MVP
ACCEPTED from regression evidence.
When production action would help containment, describe it separately and request or confirm authorization at action time. Permission to fix code is not permission to deploy instrumentation, change traffic, flip flags, rollback, or run a canary.
If intended edits cannot be separated safely from pre-existing user changes, stop and ask. After two evidence-based correction attempts fail, stop editing and revisit root cause and Plan Validation; resume only with new evidence and a revised hypothesis.
Pressure Rules
| Rationalization |
Response |
| “The cause is obvious; add the guard.” |
Reproduce and trace the actual invalid state first. |
| “Change the test so tonight's build passes.” |
Confirm whether the contract changed; otherwise fix production behavior. |
| “Catch everything so the job continues.” |
Prove isolation and consistency; catch only the expected error at its owning boundary. |
| “The visible change must be the cause.” |
Compare all plausible causes with one-variable evidence. |
Delivery
Report Problem, Root Cause, Fix, Tests, and Risk. Use precise status: reproduced, mitigated, fixed with regression evidence, or unverified. Never say fixed when only containment or correlation was observed.
1---2name: bug-fix3description: Use when executing a request to fix a defect, exception, failing test, production issue, regression, or behavior that differs from expectations.4---56# Bug Fix78Prove the causal defect, correct it at the owning boundary, and preserve the proof as a regression test.910## Required Distinctions1112| Term | Meaning |13| --- | --- |14| Symptom | The observed failure, with request/input/state and expected versus actual behavior |15| Root cause | The earliest verified condition that explains the symptom |16| Fix | The smallest change at the responsible boundary that removes the cause |1718Do not label a symptom guard, rollback correlation, or plausible guess as root cause.1920## Investigate Before Editing21221. Read applicable `AGENTS.md`, complete errors/traces, related tests, recent changes, the narrow execution path, and any canonical requirement, architecture, README, or acceptance document that defines the expected behavior.232. Reproduce the symptom or create equivalent failing evidence. If intermittent or external, gather logs, metrics, or boundary observations instead of guessing.243. List competing hypotheses and the evidence that would distinguish them. Test one variable at a time, strongest evidence first.254. Trace bad state backward to its origin. Fix at the owning boundary; avoid a downstream null guard, broad catch, retry, or default value unless that is the verified contract.2627## Plan Gate2829Before production edits, state:3031- confirmed symptom and reproduction evidence;32- root-cause hypothesis and how it was verified;33- smallest proposed fix and exact area affected;34- compatibility, data, API, concurrency, security, and operational risks that apply;35- regression-test strategy and surrounding checks;36- documentation impact, including whether the defect reveals drift in requirements, architecture, usage instructions, or existing acceptance evidence;37- existing user changes to preserve;38- authorization boundary for local edits versus deploy, rollback, feature flag, canary, merge, or other external mutation.3940Validate the plan for speculative edits, missed callers/layers, weakened semantics, unnecessary cleanup, and a smaller causal fix. Correct it before implementation.4142When the fix depends on framework, library, SDK, database, or configuration behavior, determine the project version and use version-matching official documentation. If unavailable, require authoritative pinned artifacts plus executable evidence or keep the relevant claim unverified.4344## Implement and Verify45461. Add the narrowest regression test or executable reproduction; confirm it fails for the observed defect.472. Implement only the causal correction. Do not weaken the test, change expected behavior to match the bug, swallow an exception, or bundle unrelated refactoring.483. Run the regression immediately, then relevant surrounding tests and available lint, type, build, integration, or configuration checks.494. Reproduce the original path again when feasible. Inspect Git status and diff; preserve pre-existing work and exclude unrelated edits.505. Map every plan item to exact changed files and fresh evidence.516. Synchronize only affected canonical documents. A narrow fix normally requires no new project documents; update an existing requirement, README, architecture map, or acceptance criterion only when the verified fix or confirmed contract changes its content. Never mark the MVP `ACCEPTED` from regression evidence.5253When production action would help containment, describe it separately and request or confirm authorization at action time. Permission to fix code is not permission to deploy instrumentation, change traffic, flip flags, rollback, or run a canary.5455If intended edits cannot be separated safely from pre-existing user changes, stop and ask. After two evidence-based correction attempts fail, stop editing and revisit root cause and Plan Validation; resume only with new evidence and a revised hypothesis.5657## Pressure Rules5859| Rationalization | Response |60| --- | --- |61| “The cause is obvious; add the guard.” | Reproduce and trace the actual invalid state first. |62| “Change the test so tonight's build passes.” | Confirm whether the contract changed; otherwise fix production behavior. |63| “Catch everything so the job continues.” | Prove isolation and consistency; catch only the expected error at its owning boundary. |64| “The visible change must be the cause.” | Compare all plausible causes with one-variable evidence. |6566## Delivery6768Report **Problem**, **Root Cause**, **Fix**, **Tests**, and **Risk**. Use precise status: `reproduced`, `mitigated`, `fixed with regression evidence`, or `unverified`. Never say fixed when only containment or correlation was observed.
leslieliu099