surgical-patch

Trace the symptom to the mechanism that owns the incorrect behavior, then change only that narrowest responsible layer. Avoid cleanup, renaming, and abstraction outside the fix, and add a regression test that proves the specific failure is resolved.

A surgical patch reproduces the failure first, isolates the root cause, and changes only the code layer responsible for the defect. It preserves surrounding behavior and user changes, then validates the fix with focused regression proof plus the nearest affected test gate.

Reproduce the failure first whenever it is economical to do so, since a reproduction confirms the root cause and becomes the basis of regression proof. When reproduction is too costly, capture the strongest available evidence such as logs or failing test output instead.

A minimal patch is wrong when the defect stems from a systemic design flaw affecting many layers, where a narrow fix would only mask symptoms. In those cases a broader refactor or redesign is more appropriate than a localized change.

Add only regression proof relevant to the task, typically one focused test that fails before the fix and passes after. Then run the nearest affected test gate to confirm surrounding behavior remains intact.