agentleFS
pfeffpfeff/claude-skills/skills/root-cause-depth/SKILL.md

root-cause-depth

Skill3 starsChanged 3 months agoMITView on GitHub

Use before declaring a root cause "found" in any diagnosis, debugging, incident, or postmortem task — especially when you've identified what is wrong and are about to propose a fix. Runs an evaluable stop-condition test that pushes past the proximate symptom to a named, owned mechanism. Triggers: "root cause", "RCA", "why did this happen", "the fix is to change/set X", diagnosing a misconfiguration or wrong state, incident investigation, "is that the real cause". Fire eagerly — stopping shallow is the default failure this guards against.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    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
  1. Distinctive:

    Fallback: if after a few levels no single owner is identifiable (a diffuse or emergent cause), stop descending and make "identify/assign …

    line 36
  2. Distinctive:

    Recurrence test: If the mechanism-level fix were applied, could this *class* of failure still recur through the same path?

    line 39
  3. Distinctive:

    If yes → not terminal, keep going.

    line 43

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Root-Cause Depth

A "root cause" is real only when you've reached a named, owned mechanism and chosen a response to it. Stopping at the first level that explains the symptom is the default failure. Do not stop on a vibe — run the stop condition below.

Stop condition (evaluate every candidate cause C)

C is terminal ONLY when it passes all three gates and lands on a branch. Throughout, "the action C implies" means the mechanism-level fix — what the owner would change so the correct state is produced — assumed applied. It is NOT the response branch you pick below when the mechanism is outside your control (Accept & record does not "fix" anything, so never evaluate gates 2–3 against it).

  1. Owner named. What system/process was supposed to produce the correct state? If you cannot name it (IaC, pipeline, automation, a validation that should have failed, a person/team), you are above the mechanism — keep going. Fallback: if after a few levels no single owner is identifiable (a diffuse or emergent cause), stop descending and make "identify/assign the owner" the terminal action — i.e. Escalate.
  2. Recurrence test. If the mechanism-level fix were applied, could this class of failure still recur through the same path? If yes → not terminal, keep going.
  3. Red-flag test. Is the implied action "manually correct this instance"? If yes → not terminal, keep going. The root cause is why that value was wrong and why nothing caught it.

Once C names an owner and passes 2–3, classify control — this is the actual stop:

  • In our control → terminal. Apply the structural fix to the owning system (e.g. add to IaC), not the instance patch.
  • Outside our control → terminal for descent; you can't fix the mechanism, so branch the response (one or more, not mutually exclusive):
    • Accept & record — add to a won't-fix / known-limitations list with rationale.
    • Defend — guards on our side: validation, retries, fallbacks, and/or detection/alerting so the failure is contained or caught fast.
    • Escalate — identify and engage the party who owns the mechanism.
  • Mixed ownership (partly ours, partly external) → do both: apply the structural fix to our portion AND Escalate the external portion.

The investigation stops at named mechanism + chosen branch — never at "manually fix this instance."

Anti-pattern

Anchoring on a checklist / acceptance-criterion's literal "classify the cause" wording as the stop signal. Satisfying the stated bar ≠ finding the cause that makes the fix durable. The AC is a proxy for the goal; don't optimize the proxy.

Note on severity

The depth push is uniform — always name the mechanism first. Severity affects the branch, not whether you descend: a low-blast-radius, out-of-control cause may resolve quickly to Accept & record; a shared-environment or recurring one warrants Defend + Escalate.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.