principle-fix-root-causeslisted

# Fix Root Causes A debugging fix lands at the root cause, never at the symptom. Trace every failure to the cause that produced it and correct it there — a fix applied without understanding the root cause is a coin flip. **Why:** Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. A root-cause fix is slower upfront and cheaper in total debugging time. **Pattern:** - Reproduce first. A bug you cannot reproduce is a fix you cannot verify. - Ask "why" until the chain bottoms out at a cause you can change; the proximate cause ("this variable is null") is never the root ("this runs before initialization completes"). - Resist guards that silence crashes: a nil check is a root-cause fix where absence is a legal state, and a symptom fix where it is not. - A workaround that needs a paragraph-long comment to justify it means the code is wrong. Fix the code, not the comment. - Fix the pattern, not just the instance: grep for siblings of the root cause and fix every occurrence. - When stuck, instrument instead of guessing: add logging, read the actual error, observe before hypothesizing. ## Restart bugs: suspect state before code Code does not change between runs; state does. When something "fails after restart," suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, the fix is state validation, not new code.