| name | proper-fix |
| description | Bias bug fixes and refactors toward root-cause solutions, simplification, and removal of workaround layers. Use when Codex is fixing a bug, flaky behavior, confusing edge case, or ugly conditional pileup and the obvious change looks like another patch on top of earlier patches, defensive code, or duplicated repair logic. |
Proper Fix
Overview
Diagnose the underlying failure before editing. Prefer the smallest coherent fix at the source of truth over adding another compensating condition, fallback, or band-aid downstream.
Work The Problem
Start by proving what is actually wrong.
- Reproduce the failure, trace the data flow, or read the full call chain before editing.
- Read the surrounding code, not just the failing line. Look for where the invariant should have been enforced earlier.
- Identify whether the current behavior comes from stale assumptions, split ownership, duplicated normalization, or state being repaired too late.
- Name the root cause in one sentence before choosing a fix. If you cannot do that, keep reading.
Dig Deeper Signals
Pause and inspect the design one layer deeper when any of these show up:
- The fix wants a second special case beside an existing special case.
- The code already contains words like
workaround, temporary, legacy, hotfix, or compat.
- Multiple places sanitize, default, or repair the same value.
- State becomes valid only after several follow-up mutations.
- Tests only pass when setup mirrors production accidents instead of clear rules.
- The proposed patch hides the bug instead of making invalid states impossible.
Prefer These Fix Shapes
Reach for the earliest, simplest place that can make the bad state impossible.
- Tighten the data shape where it is created or parsed.
- Move validation or normalization to the boundary instead of repeating it at call sites.
- Collapse duplicate branches into one explicit rule.
- Replace repair logic with a single authoritative state transition.
- Rewrite a small confusing section if that is clearer than threading another exception through the system.
- Delete obsolete fallback logic when the source issue is fixed.
Keep Scope Coherent
Do not turn "proper fix" into "rewrite the world."
- Prefer a local rewrite when it removes complexity inside the touched area.
- Stop expanding once the fix reaches unrelated subsystems with no direct evidence.
- If the real fix is too large for the task, make the smallest honest change and say clearly what compromise remains.
- Preserve intentional external behavior unless the user asks to change it.
- If you are choosing between a quick patch and a slightly deeper simplification, spend one more short investigation pass first.
Report The Fix Clearly
When you answer or summarize the change:
- State the root cause directly.
- State why the chosen fix is earlier, simpler, or more authoritative than the obvious patch.
- Mention any workaround code you removed or any compromise you left in place.
