root-cause-discipline
Skill0 starsChanged 4 months agoMITView on GitHub
Use when fixing bugs, especially several in a row — detects the pattern where symptom repair feels productive while the mechanism producing the symptoms stays untouched, and forces the generator into the work plan
1 other project uses a version of this.
Adopted by
Most recently taken up by
- songjiun10-collab/Senior-thinking-skillstheir own version, first seen Oct 12, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- songjiun10-collab/Senior-thinking-skills★ 87same 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 repository7 other files it gives its agents.
- agent-memorySkill
- blast-radiusSkill
- falsifier-designSkill
- orchestrator-judgmentSkill
- ratchet-not-ceilingSkill
- standing-instructionsSkill
- verify-before-judgingSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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 27
Every one of that day's fixes was the same class — a contract mismatch at a seam:
- Distinctive: line 78
If you're reporting to someone, say this explicitly — otherwise a day of root work reads as a day of nothing.
≈ “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 is the work
The score is not how many symptoms you fixed. It is how many symptom-generators you removed.
A live generator sends the symptom back — wearing a new face, costing a fresh investigation, a fresh branch, a fresh deploy.
Why this rule gets broken by people who know it
I had this written down. I violated it for an entire day anyway.
Symptom repair pays immediately and visibly. A PR opens. CI goes green. A number moves. There is something to report.
Root repair pays nothing on the day. You build a counter and no metric improves. There is nothing to show.
So busyness impersonates progress. I shipped ten PRs while leaving the mechanism intact, and felt productive the whole time.
Every one of that day's fixes was the same class — a contract mismatch at a seam:
| Symptom | Actual root |
| Search returns nothing for a common term | Filter applied after truncation, not before |
| Model emits malformed JSON | Prompt and validator assume different escaping |
| Monitor alarms for 12 cycles | A comment says "ratchet"; nothing enforces it |
| Deploy kills the running job | Gate's cost model ≠ scheduler's slot semantics |
| Instrument reads empty | Counter built, read path never built |
| Collector never runs | Built, never wired |
I picked them up one at a time. The thing generating them — dozens of scattered, independently-defined decision paths — never entered the plan.
Self-detection
You are picking up symptoms if any of these are true:
- Three or more defects of the same class this week
- Each fix reveals the next one (serial discovery = you never mapped the class)
- Your work plan has zero items whose purpose is "make this class impossible"
- Some stage of the project has been logged as "stalled" across many reports — that's usually the root; it's stalled because it's hard
- "Something more urgent right now" for the third time in a row — that's not priority, that's avoidance
How to apply
- Name the class before writing the fix. "What is this an instance of?" Once you've named the same class three times, stop fixing instances.
- If the root is too big, make it countable first. This is the unlock. My root item sat untouched for four days because I couldn't tell whether it was getting better. The answer wasn't to fix it — it was to build a reproducible counter and a ratchet. You cannot reduce what you cannot count.
- Seal before you reduce. A ratchet that forbids increase is worth more than a
partial reduction. Stop the growth first. (See
ratchet-not-ceiling.) - Record the root even when you only fix the symptom. Otherwise the third occurrence still looks novel.
- Every work plan gets at least one root item. A plan that is entirely symptoms is the wrong plan.
Expect no same-day payoff
Root work doesn't move today's numbers. That is what correct root work looks like. What it moves is next month's defect rate.
If you're reporting to someone, say this explicitly — otherwise a day of root work reads as a day of nothing.
The counterweight
Rejected work is also recorded work. Before declaring something a root and attacking it, search the module for prior investigation — good codebases record why they decided not to fix something, in comments right next to the code.
But read the scope of that rejection carefully. "We rejected loosening the matcher because precision collapsed" does not mean "we rejected making byte-identical strings collapse." Adjacent is not the same.
Reading a rejection too narrowly means redoing settled work. Reading it too broadly means abandoning work that was never rejected. Both are losses.
Related
ratchet-not-ceiling— the mechanism for sealing a classblast-radius— mapping the class before fixing
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.