# Principle Fix Root Causes

> Requires diagnosis and repair of root causes. Apply when debugging any failure or regression.

- Skill: `bostonaholic/principle-fix-root-causes` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bostonaholic/principle-fix-root-causes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bostonaholic/principle-fix-root-causes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bostonaholic (https://skillmd.com/u/bostonaholic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bostonaholic/principle-fix-root-causes

---


# 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.