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
- 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.
This repository (Asymmetric-al/core)
Vendored from p3-stack (MIT) at commit 09909eb. Provenance is in references/upstream.md. On conflict, the current user request, root AGENTS.md, the nearest nested AGENTS.md, and the matching docs/ai/rules/* rulebook win over this skill.
- Explicit invocation only: use it when the user invokes
/principle-fix-root-causes (Claude Code, Cursor, T3 Code) or $principle-fix-root-causes (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.
- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.
Edit this canonical copy in docs/ai/skills/principle-fix-root-causes/, then run bun run skills:sync and bun run skills:verify.
1---2name: principle-fix-root-causes3description: "Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/asymmetric-al/principle-fix-root-causes7---89# Fix Root Causes1011When debugging, do not fix symptoms. Trace every problem to its root cause and fix it there.1213**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.1415**Pattern:**1617- Reproduce first18- Ask "why" until you hit the root cause19- Do not add guards (adding a nil check to silence a crash is a symptom fix)20- If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)21- Check for the pattern, not just the instance (grep for the same pattern, fix all instances)22- When stuck, instrument. Don't guess (add logging, read the actual error)2324**Restart bugs: suspect state before code**2526When 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.2728<!-- CORE-OVERLAY-START -->2930## This repository (Asymmetric-al/core)3132Vendored from [p3-stack](https://github.com/uzairansaruzi/p3-stack) (MIT) at commit `09909eb`. Provenance is in `references/upstream.md`. On conflict, the current user request, root `AGENTS.md`, the nearest nested `AGENTS.md`, and the matching `docs/ai/rules/*` rulebook win over this skill.3334- Explicit invocation only: use it when the user invokes `/principle-fix-root-causes` (Claude Code, Cursor, T3 Code) or `$principle-fix-root-causes` (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.35- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.3637Edit this canonical copy in `docs/ai/skills/principle-fix-root-causes/`, then run `bun run skills:sync` and `bun run skills:verify`.3839<!-- CORE-OVERLAY-END -->