name: principle-fix-root-causes description: "Apply when debugging. Trace the symptom to its cause, reproduce first, resist guard-band patches."

Fix Root Causes

A symptom patch leaves the real bug in place and adds a second thing to reason about. Trace every failure to the mechanism that produces it and fix that.

Why: Guard-band patches accumulate until the original cause is unfindable, and each one is a new thing to debug.

Pattern:

• Reproduce first. A bug you cannot reproduce, you cannot prove fixed.
• Ask why until the next why is outside the system.
• Do not add a guard that swallows the crash. Fix the producer.
• If the workaround needs a paragraph of comment, the code is wrong.
• Grep for the same pattern and fix the class, not the instance.
• Instrument when stuck. Read the actual error. Do not guess.
• Restart-only failures: suspect stale state (config, cache, lock, serialized files) before the code.