principle-fix-root-causes

Guides debugging by tracing symptoms to root causes instead of applying symptom-level workarounds.

Updated Mar 27, 2026
One-click install
npx skills add https://github.com/gmackie/agent-skills --skill principle-fix-root-causes-gmackie
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: principle-fix-root-causes
Source: https://github.com/gmackie/agent-skills/tree/main/skills/principle-fix-root-causes
Command: npx skills add https://github.com/gmackie/agent-skills --skill principle-fix-root-causes-gmackie

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging often produces quick symptom fixes—nil checks, guards, and workarounds—that silence crashes while leaving the real bug in place. These accumulate into fragile, hard-to-reason-about code. This Skill enforces a disciplined root-cause debugging methodology so fixes address the actual defect. ## Core Features & Use Cases - Root-Cause Tracing: Reproduce the bug first, then ask "why" repeatedly until the underlying cause is found, rather than patching the visible symptom. - Anti-Pattern Detection: Resist nil-check guards that silence crashes, treat paragraph-long justification comments as a signal the code is wrong, and grep for the same pattern to fix all instances, not just one. - Restart Bug Diagnosis: When something fails after restart, suspect stale persistent state (config files, caches, lock files, serialized state) before suspecting code, since code does not change between runs. - Use Case: A crash reappears after every deploy despite added null checks. Apply this Skill to reproduce the failure, trace it to a corrupted cache file, and add state validation as the real fix. ## Quick Start Ask the AI to debug the current failure by tracing it to its root cause instead of adding a guard or workaround.

Frequently Asked Questions about principle-fix-root-causes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the root cause of a bug instead of patching symptoms?▼

Reproduce the bug first, since an unreproducible bug cannot have a verified fix. Then ask "why" repeatedly until you reach the underlying cause, and fix it there rather than adding guards that only silence the visible symptom.

How to debug a failure that only happens after restart?▼

Suspect stale persistent state before code, because code does not change between runs but state does. Check config files, caches, lock files, and serialized state; if clearing a state file restores behavior, prioritize state validation as the fix.

Why is adding a nil check to stop a crash considered a bad fix?▼

A nil check that silences a crash is a symptom fix: the real defect remains and the workaround makes the system harder to reason about. Trace why the value is nil and fix that cause instead of guarding against it.

What should I do when stuck and unable to find a bug's cause?▼

Instrument the code instead of guessing. Add logging and read the actual error output to gather evidence about the failure, then continue tracing the causal chain until the root cause is identified.

When is a workaround acceptable instead of a root-cause fix?▼

If a workaround needs a paragraph-long comment to justify it, the code is wrong and should be fixed instead. Symptom fixes accumulate over time and increase total debugging time, so root-cause fixes are preferred despite higher upfront cost.