agentleFS
Ingramradical235Ingramradical235/anty-framework/skills/root-cause/SKILL.md

root-cause

Skill1 starsChanged 8 months agoMITView on GitHub

Structured root cause analysis using WHERE (MECE decomposition) then WHY (causal structure diagrams) pipeline. Includes coin-flip detection, logical-leap detection, and vicious cycle intervention. Use when buffer enters YELLOW/RED, when metrics stall, or when Actions execute but don't produce results.

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 4

    Distinctive

    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:

    Read the causal chain bottom-to-top, inserting "therefore" between nodes.

    line 77
  2. Distinctive:

    If there's a logical gap, an intermediate cause is missing.

    line 84
  3. Distinctive:

    Never skip from symptom to conclusion.

    line 88
  4. Distinctive:

    When applying this framework, produce the FULL output immediately.

    line 146

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “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 Analysis (WHERE -> WHY)

When to Apply

  • Buffer enters YELLOW or RED zone
  • Actions executed but metrics not moving (Layer 1 OK, Layer 2 stalling)
  • Significant KPI decline detected
  • Review engine Question 5 triggers (was root-cause analysis correct?)
  • Any time "why isn't this working?" is asked

Core Framework

Stage 1 — WHERE (Locate the Problem)

MECE decomposition of the underperforming Goal into Drivers, identifying which specific Driver(s) are stalling.

Goal buffer: YELLOW (45% consumed, 34% progress)

WHERE analysis (MECE decomposition by Driver):
  Social growth:      45% of target  <- GAP HERE
  Referral program:   20% of target  <- GAP HERE
  SEO content:        60% of target  (on track)
  LP A/B testing:     30% of target  (too early)
  Nurture emails:     10% of target  (not started)

Identified: Social growth and Referral are primary gaps.

WHERE must complete before WHY begins. This is strict and sequential.

Stage 2 — WHY (Causal Structure Diagram)

Starting from the WHERE-identified gap, build a causal structure by asking "Why?" iteratively, one layer at a time. Each node carries a verification status.

Social growth stalling (WHERE-identified gap)
  |
  +-- Post engagement declining [VERIFIED - analytics data]
  |     +-- Content not resonating with ICP [HYPOTHESIS]
  |     |     +-- Tone mismatch [HYPOTHESIS]
  |     |     +-- Topic mismatch (features vs pain-points) [VERIFIED]
  |     +-- Posting at wrong times [DISPROVEN - analytics show optimal]
  |
  +-- Follower growth rate declining [VERIFIED]
        +-- No engagement with other accounts [VERIFIED] <- ACTION TARGET
        +-- Algorithm change [UNCONTROLLABLE]

Causal Node Types

TypeMeaningVisual
verifiedConfirmed by data/factsSolid line
hypothesisNot yet verifiedDashed line
disprovenChecked and ruled outMarked X
uncontrollableOutside our controlMarked X
action_targetSelected for countermeasureHighlighted

Built-in Safeguards

1. Coin-Flip Detection

Reject causes that are merely the negation of the problem:

  • BAD: "Social growth is stalling because we're not growing socially" (coin-flip)
  • GOOD: "Social growth is stalling because post engagement rate dropped from 4.2% to 1.8% after we shifted from pain-point content to feature announcements"

Causes must describe CONCRETE MECHANISMS, not restatements.

2. Logical-Leap Detection ("Therefore" Reverse-Read Test)

Read the causal chain bottom-to-top, inserting "therefore" between nodes. It must read naturally:

"Topic mismatch (features vs pain-points), THEREFORE content not resonating,
THEREFORE post engagement declining, THEREFORE social growth stalling"

If there's a logical gap, an intermediate cause is missing. Add it.

3. One Step at a Time

Never skip from symptom to conclusion. Each WHY drills exactly one causal layer deeper, potentially branching into multiple parallel causes.

Vicious Cycle Detection & Intervention

Detection

Analyze the causal structure diagram for loops (cycles in the directed graph):

Vicious cycle found:
  No content ideas -> Low post frequency -> Low engagement
  -> Low follower growth -> Less audience feedback -> No content ideas
  (loop restarts)

Intervention (4-Step Process)

  1. Identify the loop in the causal graph
  2. Evaluate each node for intervention viability:
    • Controllable by us? (exclude external factors)
    • Executable at low cost?
    • High ripple effect when broken?
  3. Project the virtuous cycle that results from intervention
  4. Generate concrete Actions via 3-option choice
Best intervention point: "No content ideas" (controllable, low cost, high ripple)

Projected virtuous cycle:
  Content ideas from research -> Higher post frequency ->
  Better engagement -> Follower growth -> More feedback ->
  More content ideas (positive loop)

Decision Rules

  1. WHERE before WHY — always locate the gap before investigating causes
  2. MECE decomposition — WHERE analysis must be mutually exclusive, collectively exhaustive
  3. Verification status is mandatory — every causal node must be tagged
  4. Hypotheses must be tested — don't build Actions on unverified hypotheses
  5. Action targets on verified nodes — only target verified, controllable causes
  6. Vicious cycles get priority — breaking a negative loop has outsized impact

Anti-Patterns to Detect

Anti-PatternSignalResponse
Coin-flip causeCause is negation of problem"This restates the problem. What's the specific mechanism?"
Logical leapGap in causal chain"Insert 'therefore' between these nodes. There's a missing step."
Skipping WHEREJumping to WHY without locating gap"First, which specific Driver is stalling? MECE decompose."
Unverified action targetsBuilding Actions on hypotheses"This cause is unverified. Verify before investing resources."
Ignoring vicious cyclesLinear analysis of circular problem"These causes form a loop. Breaking the cycle has outsized impact."
Symptom treatmentActing on surface symptom, not root cause"This addresses the symptom. Let's drill one more layer to the mechanism."

Anticipative Execution Reminder

When applying this framework, produce the FULL output immediately. Do not ask the founder which parts to analyze or which options to consider. Infer from business context, present the complete deliverable, and let the founder react to concrete work — not abstract choices.

Download now (ZIP)

  • Other versions24 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 24

    1. crbnos/carbon★ 2.8ksame name
    2. formancehq/ledger★ 1.4ksame name
    3. jjanczur/tyran★ 81same name
    4. Vesely/skills★ 28same name
    5. composio-community/support-skills★ 18same name
    6. lalulali/vespyr★ 11same name
    7. nadirali1350/vetted★ 5same name
    8. Xnadir/vetted★ 5same name
    9. quocld/hephaestus-agent-skills★ 4same name
    10. MissingPackage/nightshift★ 3same name

    14 more not listed

    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.

  • Used alongsideProjects with it also use prove-it, explain and 6 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • Neko-Catpital-LabsSkill

      prove-it

      Shared evidence rule for investigating, diagnosing, debugging, proving, or explaining what happened or why for any problem or situation: do not assert something is fixed, working, passing, merged, or running unless you personally observed it this turn and can show what you saw; do not assert it was caused by X until a repro and controlled isolation prove that cause.

      Also in 3 projects that use this

    • sunnyclinches44Skill

      explain

      Explains code using real-world analogies and ASCII diagrams

      Also in 5 projects that use this

    • renatorozasSkill

      grill

      Adversarial code review. Don't let me ship until the changes pass your scrutiny.

      Also in 3 projects that use this

    • Microsoft AzureSkill

      design

      Design rules and conventions for the API Center Portal. Use when editing detail pages, card components, badges, layout, navigation, sidebars, or headers. Covers badge styling, metadata placement, page navigation patterns, and layout alignment.

      Also in 4 projects that use this

    • Hugging FaceSkill

      implement

      Make tests pass. Invoke after /write-tests produces failing tests.

      Also in 3 projects that use this

    • MicrosoftSkill

      handoff

      Compact the current conversation into a handoff document for another agent to pick up.

      Also in 3 projects that use this

  • In this repository24 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

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.