principle-fix-root-causes git:20260904.5a122b3A

Immutable. This exact content is served forever at /api/v1/blob/ccf7753f2e9a75ce.

---
name: principle-fix-root-causes
description: 'Requires diagnosis and repair of root causes. Apply when debugging any failure or regression.'
user-invocable: false
---

# Fix Root Causes

Land debugging fixes at the root cause, never at the symptom.

- Reproduce before fixing; an unreproduced bug cannot be verified.
- Ask why until reaching a changeable cause beyond the proximate symptom.
- Add nil guards only when absence is legal; otherwise correct why absence occurred.
- Replace paragraph-justified workarounds with a code fix.
- Grep for sibling instances of the root cause and fix every occurrence.
- When stuck, instrument, read the actual error, and observe before hypothesizing.
- For failures after restart, suspect stale persistent state first: config files, caches, lock files, serialized state.
- If clearing a state file restores behavior, add state validation instead of unrelated code.