root-cause-first
Skill30 starsChanged 4 months agoMITView on GitHub
Debugging discipline. Use whenever diagnosing a bug, error, test failure, crash, regression, flaky behavior, or unexpected output, and especially before applying any fix. Also trigger when a previous fix attempt did not work and another attempt is about to be made.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Tcuzzo/backs-aios-skillstheir own version, first seen Nov 3, 2026
- cohen-liel/agent-skillstheir own version, first seen Jun 3, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- cohen-liel/agent-skills★ 15same name
- Tcuzzo/backs-aios-skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- delegate-and-verifySkill
- evidence-audited-analysisSkill
- finish-the-turnSkill
- lessons-ledgerSkill
- minimal-diffSkill
- outcome-first-writingSkill
- plain-handoffSkill
- verified-doneSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Reproduce it: Run the failing thing and watch it fail.
- Distinctive: line 19
When a fix attempt fails, write down (in a scratch file or your working notes) before doing anything else:
- Distinctive: line 30
After two failed fix attempts, stop fixing and restart diagnosis from scratch:
- Distinctive: line 35
If available, hand the evidence (not your theory) to a fresh-context subagent and ask it to diagnose independently.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Root Cause First
Fix causes, not symptoms. A fix applied to an undiagnosed problem is a guess, and guesses compound: each one changes the system, making the real cause harder to see.
Before you fix anything
- Reproduce it. Run the failing thing and watch it fail. If you cannot reproduce the failure, you cannot know your fix works, and you say so instead of claiming a fix.
- Trace it. Follow the failure from the symptom back to the cause: read the actual error, read the code path that produced it, inspect the actual state (logs, variables, files, network) rather than assuming it. Stop tracing only when you can explain the mechanism: "X happens because Y does Z."
- Beware pattern-matching. A signal that pattern-matches a known failure may have a different cause. "This looks like the usual CORS issue" is a hypothesis, not a diagnosis. Verify the mechanism before acting on the resemblance, especially before any state-changing action like a restart, delete, or config edit.
- Then fix the cause. If the honest fix is upstream (a data problem, a wrong assumption in a caller, a stale dependency), fix it there. Do not patch the symptom downstream and call it done. If a downstream patch is genuinely the right short-term call, label it a bridge and state the debt it creates.
The failed-approach ledger
When a fix attempt fails, write down (in a scratch file or your working notes) before doing anything else:
- What you tried
- What you expected
- What actually happened
- What this rules out
Then, and only then, form the next hypothesis. The ledger exists to enforce one rule: never retry a failed approach verbatim. If you find yourself making the same edit a second time, or re-running the same command hoping for a different result, stop. That is the signal you are guessing.
The two-failure rule
After two failed fix attempts, stop fixing and restart diagnosis from scratch:
- Re-read the original error with fresh eyes. The answer is often in a line you skimmed.
- Question your framing: is the bug even where you think it is? Check one layer up and one layer down.
- Shrink the reproduction: find the smallest input or code path that still fails.
- If available, hand the evidence (not your theory) to a fresh-context subagent and ask it to diagnose independently. Your accumulated assumptions are now part of the problem.
Why this matters
The most expensive debugging sessions are not the hard bugs. They are the easy bugs treated with a sequence of confident guesses, each of which added noise. Diagnosis feels slower than guessing and is almost always faster.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.