# Fixing Root Causes

> Traces a bug or failure to its root cause and fixes it there instead of patching the symptom. Use when the user says "find the root cause", or when debugging a crash, failing test, regression, or "fails after restart" bug, or when a fix would add a guard, retry, or workaround to silence an error.

- Skill: `bostonaholic/fixing-root-causes` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add bostonaholic/fixing-root-causes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bostonaholic/fixing-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-11-16
- Page: https://skillmd.com/skills/bostonaholic/fixing-root-causes

---


# Fix Root Causes

When debugging, do not fix symptoms. Trace every problem to its root cause and fix it there.

**Why:** Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. Root-cause fixes are slower upfront but reduce total debugging time.

**Pattern:**

- Reproduce first
- When docs and code disagree, decide which is the bug per the [docs and code rules](shared/docs-vs-code.md)
- Ask "why" until you hit the root cause
- Do not add guards (adding a nil check to silence a crash is a symptom fix)
- If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)
- Check for the pattern, not just the instance (grep for the same pattern, fix all instances)
- When stuck, instrument. Don't guess (add logging, read the actual error)

## Restart bugs: suspect state before code

When something "fails after restart," suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, prioritize state validation as the fix.

