agentleFS
shawnclyborshawnclybor/clybor-claude-tooling/.claude/skills/five-whys/SKILL.md

five-whys

Skill6 starsChanged 29 days agoMITView on GitHub

Root-cause analysis protocol for when something breaks unexpectedly. Use when a tool call fails twice, a service returns unexpected results, a workflow produces wrong output, or any situation where retrying blindly would waste time. Triggered by "why did that break", "what went wrong", "debug this", or the Two Strikes Rule. Use proactively — if you catch yourself about to retry the same failing call a third time, stop and invoke this instead. Diagnosis ends at a VERDICT, not at a governance write — six verdicts are legal, including "cause not established" and "external defect outside my control". Do NOT use for routine errors with obvious fixes (typos, missing params, wrong file path).

9 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use pre-mortem.

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.
  • Ingramradical235Skill

    pre-mortem

    Pre-mortem analysis, scenario planning, future state narratives, and contingency frameworks. Use before finalizing any Strategy Kernel, when planning major initiatives, or when preparing Plan B triggers.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 10 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When something breaks and the cause isn't obvious, walk through this protocol before retrying or working around the problem.

    line 8
  2. Distinctive:

    Write one sentence: what happened vs.

    line 32
  3. Distinctive:

    If you do not have the input:

    line 42
  4. Very specific:

    Use Sequential Thinking for the chain.

    line 56
  5. Distinctive:

    Keep going past the surface-level "what" and into the structural "why." "The API returned an error" is a symptom.

    line 69
  6. Distinctive:

    When the cause is external, reach for a mechanism or a fact.

    line 93
  7. Distinctive:

    Search the relevant rule file's Known Issues section

    line 97
  8. Distinctive:

    Check the Pre-Flight Checklist — did we skip a step?

    line 98
  9. Distinctive:

    If the issue IS documented and we missed it → that's Verdict C.

    line 99
  10. Distinctive:

    Do only what the verdict licenses (right-hand column above).

    line 120
  11. Distinctive:

    Cascade check: If the fix spawns a new error class, or scope multiplies through accumulated governance, stop and escalate.

    line 122

“Common” is measured: kept by at least 6 in 10 of the 8 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

Five Whys — Root Cause Analysis

When something breaks and the cause isn't obvious, walk through this protocol before retrying or working around the problem.

Why this matters: blind retries are the #1 source of wasted time and compounding errors. A wrong guess can corrupt data, send to the wrong destination, or overwrite files with stale state. Five minutes of root-cause analysis now saves thirty minutes of cleanup later.

What this protocol produces

A verdict. Not a governance update.

Diagnosis ends when you can name what happened and how well you know it. What to do about it is a separate decision, made after the verdict, from the verdict. Six verdicts are legal (Step 4). Writing a rule is one possible consequence of one of them.

Why this is stated first. An earlier version of this skill ended "Every Five Whys should end with a governance update." That single line corrupted the diagnosis upstream of itself. If the only legal ending is a rule, the search stops at the first cause that can be written as a rule, not at the true cause. Causes that aren't rule-shaped have nowhere to go, so the protocol pressures you to reframe them until they are.

When to invoke

  • A tool call fails twice with the same or similar error (Two Strikes Rule)
  • A service returns unexpected/wrong data (stale, empty, mis-routed)
  • A workflow produces incorrect output despite correct-looking inputs
  • The user reports something broke that previously worked
  • You catch yourself about to retry something that already failed twice

The Protocol

Step 1 — State the problem, and get the input before diagnosing the output

Write one sentence: what happened vs. what was expected. Be specific. Include the tool name, the exact input, and the actual output.

A vague problem statement ("the X thing broke") leads to a vague investigation. Specificity narrows the search space immediately.

HARD GATE — no input, no root-cause claim

You must have the actual input that produced the failure. Not a reconstruction of it. Not an inference from the error text. The real thing.

An error message is a floor on what went wrong, not a ceiling. Distinct bugs routinely converge on byte-identical errors — a parameter that was omitted and a parameter that was sent but mangled in serialization both arrive undefined and produce the same message. The error cannot tell you which one you have.

If you do not have the input:

  1. Go get it. Scroll the transcript, read the log, or ask the user for the raw call. This is usually one question and it is cheaper than every step that follows.
  2. If you cannot get it, you have NOT found a root cause. That is Verdict D (Step 4) — a legal, complete ending to this protocol. Go there. Do not manufacture a cause just to have something to write.
  3. Never substitute a reconstructed input for the real one and then proceed as though you had identified the cause.

Reproduction is a sufficiency test, not an identification. Successfully reproducing a candidate cause proves it can produce the symptom. It proves nothing about whether it did. Green probes against a reconstruction feel like proof and are not — and confirming evidence quiets the instinct that would otherwise notice the story is straining.

Distrust a cause that arrives pre-written. If the explanation is already in a governance file and fits the symptom perfectly, that is grounds for more scrutiny, not less. Availability plus fit is exactly the condition under which diagnosis converges on the wrong answer while feeling rigorous. Checking a documented cause is only diligence once you have ruled out the alternatives that produce the same symptom.

The tell to watch for. If your causal chain requires an implausible actor — someone who read half a sentence, ignored a rule they'd just consulted, or made an error they had every reason not to make — that strain is data. A true account usually needs no such assumption. Ask what else produces this symptom without requiring anyone to behave absurdly.

Step 2 — Ask "Why?" iteratively

Use Sequential Thinking for the chain. Each thought = one "Why?" iteration. Set totalThoughts: 5 initially. Use isRevision: true if a later "Why?" invalidates an earlier assumption.

Each answer becomes the subject of the next "Why?" Stop when you reach a cause that explains the symptom — you don't always need all five levels.

Problem: Draft landed on wrong record
Why 1?  → The tool resolved the wrong target ID
Why 2?  → ID resolution uses fuzzy matching, not exact lookup
Why 3?  → We passed instructions text instead of an explicit ID
Why 4?  → We didn't search for the target first to get its ID
CAUSE: No find-first step before the write

Keep going past the surface-level "what" and into the structural "why." "The API returned an error" is a symptom. "We sent a property name with a missing trailing space" is a cause.

Stop when the cause explains the symptom — not when it becomes actionable. These are different stopping points and the second one is a trap. "Actionable" smuggles in "actionable by me," which quietly excludes every cause that lives in someone else's code. A cause you cannot act on is still the cause.

Step 3 — Locate the cause: inside or outside your control

Before asking what to do, ask whose defect it is. This single question is what keeps the protocol from converting other people's bugs into your process burden.

LocusMeaningExamples
Ours — processWe have a step and didn't follow it, or we don't have a step and shouldSkipped find-first; no pre-flight check for date windows
Ours — mechanismOur code, config, script, prompt, or dataA wrong ID in a lookup table; a broken one-liner; a bad hook
Theirs — externalA defect in a component we neither own nor can patchA third-party MCP server bug; a vendor API quirk; a client app's cache

The bucket determines which verdicts are available in Step 4. Getting it wrong is the most expensive error in this protocol, because the failure is silent — you end up with a plausible rule, a real bug still in place, and no signal that anything went wrong.

The anti-pattern this bucket exists to stop

An external defect earns a FACT you look up. It never earns a BEHAVIOR you must perform.

A fact (a Known Issues row, a diagnostic signature, a canonical call shape) is free until you hit the symptom, and then it saves you. A behavior (a hard rule, a mandated pre-flight step, a "remember to always…") costs you on every unrelated request forever — and cannot fix someone else's bug, because the bug is not in your behavior.

The shape this takes in practice: a third-party tool has an intermittent serialization defect. Five-whys runs on it and produces a page of behavioral prose about how to call the tool so the defect doesn't fire. The prose doesn't work — the defect fires anyway, sometimes while the rule is open in context. Meanwhile, measurement shows the tool erroring in a few percent of sessions and never being called at all in most of them. The loud, explained minority absorbed the attention the silent majority needed — and the majority was ours, and closed by a hook script that blocks the write until the tool has actually run. Writing governance about someone else's bug feels like progress, which is exactly what makes it expensive.

When the cause is external, reach for a mechanism or a fact. Never a behavior.

Also check, before proposing anything — is this a known issue?

  1. Search the relevant rule file's Known Issues section
  2. Check the Pre-Flight Checklist — did we skip a step?
  3. If the issue IS documented and we missed it → that's Verdict C. The gap is adherence or discoverability, not a missing rule. Writing the rule a second time is not the fix.

Step 4 — Reach a verdict

Name one. This is where diagnosis ends.

#VerdictWhen it appliesAvailable consequences
ARoot found — governance change warrantedLocus is ours — process. The behavior genuinely closes the gap, and the pattern has recurred or the blast radius justifies permanent cost.Rule / pre-flight item / Known Issues row. Prefer a script that exits non-zero over prose — honor-system gates fail.
BRoot found — no governance changeLocus is ours, but the fix is a mechanism (code, config, ID, script), or it's a genuine one-off where a rule would over-fit to n=1.Just fix it. Write nothing.
CRoot found — already documentedThe issue is in Known Issues and we missed it.Fix the instance. Ask why it wasn't found — that's a discoverability problem, possibly a routing gap. Do NOT re-document.
DCause not establishedYou don't have the real input, or several paths produce this symptom and you can't discriminate.Enumerate candidate paths. Name the check that would discriminate. Label it CANDIDATE PATHS — cause not established. Stop.
EExternal defectLocus is theirs. You cannot patch it.Ladder, in order — (1) mechanical containment (script, wrapper, hook); (2) a fact (Known Issues row with a diagnostic signature); (3) escalate upstream (file the bug); (4) accept and name it. Never a behavioral rule.
FWrong skillThe chain bottoms out at a silent framing assumption, not a fixable root.Hand to why-diagnostic.

Every verdict is a complete, legal ending. D and E are not failures of the protocol — they are frequently the correct answer, and the honest one. A run that ends "this is a bug in a tool we don't own, here's the signature so we recognize it faster next time, we can't fix it" is a successful run.

A is the narrowest verdict, not the default. It requires all three — locus is ours, the locus is process specifically, and the behavior actually closes the gap. Miss any one and you're in B, C, or E.

Step 5 — Act on the verdict

Do only what the verdict licenses (right-hand column above). Two guardrails:

  • Cascade check. If the fix spawns a new error class, or scope multiplies through accumulated governance, stop and escalate.
  • The gate points one way. Promoting a hard rule should require a five-whys run. Running five-whys does not require promoting a rule. This protocol is the gate for rule-writing, not a pipeline into it.

Step 6 — Report

Tell the user:

  • What broke (Step 1)
  • The cause (Step 2), or that it isn't established (Verdict D)
  • Whose defect it is (Step 3) — ours-process, ours-mechanism, or theirs
  • The verdict (Step 4), by letter and name
  • What you did — and what you deliberately did not do. If you declined to write governance, say so and say why. A silent non-write is indistinguishable from forgetting.
  • Whether anything needs manual intervention

Key principle

The goal is to know what actually happened — accurately enough to act, or honestly enough to say you can't yet.

"Make it never break this way again" is a good outcome when the breakage is yours to prevent. When it isn't, insisting on that outcome produces a rule that can't work and a bug that doesn't care. Governance cannot fix what you do not control.

When to use debugger or error-coordinator instead

  • debugger — if the failure has a reproducible trigger and you need to find a root cause rather than walk a protocol. Reproduction-first, evidence-driven. Use debugger first; fall back to five-whys if debugger cannot reproduce or cannot find a root cause. (Reproduction still only proves a cause can produce the symptom — see the Step 1 gate.)
  • error-coordinator — if multiple parallel agents or tasks failed in the same run and the failures might share an upstream cause. Correlates symptoms; surfaces shared root causes.

Five-whys is the protocol for unexpected failures with no reproduction. debugger is the executor when reproduction exists. Both end in a verdict.

Related skill: why-diagnostic

five-whys and why-diagnostic are paired, not redundant.

  • five-whys (this skill) is for incident response. Something broke that previously worked, and the chain bottoms out at a cause you can name. RCA assumes a cause exists — it does not assume the cause is yours, or fixable.
  • why-diagnostic is for frame clarification — "why did this happen" moments where the question may be asked inside the wrong frame. The chain bottoms out at a silent assumption, not a fixable root.

Tool failed twice and retry is dangerous → five-whys. "Why did the agent do X" / "why is this design right" → why-diagnostic. Both fit → why-diagnostic first to check the frame, then five-whys.

<!-- INSIGHT-CHAIN v1 -->

The insight chain

Type "insight" to find the trio. Each step ends by recommending the next one.

#SkillRequired?What it gives you
1five-whys or why-diagnosticOptionalThe cause, or an honest "cause not established"
2insight-crystallizerAlwaysThe lesson, filed so it outlives the chat
3insight-builderOptionalA built fix, tested twice, proven shipped
4insight-promotionOptionalThe lesson made always-on, pointing at the fix

You are here: step 1. Fix before promote: a rule written before its fix is proven tells every future session to follow a guess.

Next step (end every run with this)

Finish with this block, filled in. Short, plain, numbered.

Next step
1. <one action, who does it>  (recommended)
2. <alternative, if any>
Why: <one sentence>
  • Always next: insight-crystallizer. File the verdict, the evidence and the fix you propose so the lesson outlives this chat.
  • Then, if the verdict says something must change, insight-builder builds and proves it.
  • Verdict "cause not established": still crystallize what you ruled out. Recommend the one test that would settle it.

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.