diagnose-root-causes
Skill1 starsChanged 2 months agoMITView on GitHub
Reproduce a bug, regression, hang, slow path, or flaky test and prove its root cause by testing hypotheses. Not for the fix (engineer-code-change) or live incidents (respond-to-production-incidents).
In this repository21 other files it gives its agents.
- change-production-data-safelySkill
- craft-contextual-uiSkill
- engineer-code-changeSkill
- engineer-reliable-data-pipelinesSkill
- engineer-secure-systemsSkill
- evaluate-agent-behaviorSkill
- handle-sensitive-data-safelySkill
- infer-intent-before-codingSkill
- migrate-contracts-safelySkill
- operate-production-safelySkill
- orchestrate-long-running-workSkill
- plan-decision-complete-changeSkill
- ponytailSkill
- publish-verified-github-changeSkill
- release-production-changesSkill
- respond-to-production-incidentsSkill
- review-code-with-evidenceSkill
- route-ultracode-subagentsSkill
- verify-end-to-endSkill
- write-durable-documentationSkill
- write-tests-that-prove-behaviorSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
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
Read the repository instructions.
- Distinctive: line 15
If reproduction is unsafe or impossible, work from logs, traces, state, and history, and label every conclusion by the strength of its …
- Distinctive: line 21
Keep a short ledger and update it as you go:
- Distinctive: line 33
Never declare a cause after merely swallowing an error, adding a fallback, raising a timeout or retry count, clearing state, weakening a …
- Distinctive: line 35
Keep experiments reversible and isolated.
- Distinctive: line 47
When a fix is explicitly requested, hand the proven causal seam to engineer-code-change: add or name a regression check, correct the …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Diagnose Root Causes
Find the earliest causally relevant divergence that explains the symptom. Separate the trigger, the root cause, and contributing conditions. Treat the user's theory, the error message, and suspicious-looking code as leads, not conclusions.
Establish the failure
- Read the repository instructions. Write down actual versus expected behavior, the triggering input, environment, version, timing, frequency, and last known good state.
- Build the smallest faithful, safe reproduction through the real entry point or its closest substitute. Keep the exact command, request, fixture, interaction, and output.
- Classify the symptom: deterministic, intermittent, environment-specific, or pre-existing baseline behavior.
- If reproduction is unsafe or impossible, work from logs, traces, state, and history, and label every conclusion by the strength of its evidence.
Falsify hypotheses
Trace backward from the failing boundary through inputs, transformations, state ownership, persistence, caches, external calls, configuration, concurrency, retries, and timeouts until the invariant first diverges.
Keep a short ledger and update it as you go:
H1: <hypothesis> | explains: <evidence> | contradicted by: <evidence or "nothing yet"> | cheapest check: <command or inspection>Change one discriminating variable at a time. Prefer focused instrumentation, history bisection, reduced inputs, comparison against a known-good reference, or delta debugging over speculative edits. Retire disproven hypotheses explicitly.
A root cause must explain the complete causal chain and why the reproduced conditions trigger it. A symptom that disappears is not proof.
Do not mask the symptom
Never declare a cause after merely swallowing an error, adding a fallback, raising a timeout or retry count, clearing state, weakening a test, or wrapping an invariant in a defensive check. Those hide the divergence; they do not explain it.
Keep experiments reversible and isolated. Do not mutate production, shared data, credentials, or external systems without explicit authority. Remove temporary instrumentation before finishing unless durable observability is part of an authorized fix.
Stop and ask when
- the only remaining discriminating check needs production access or a destructive action;
- the evidence supports two causes equally and only the user can supply the missing fact;
- the request said "diagnose only" and you are tempted to edit.
Done when
For diagnosis-only work: the symptom, root cause, causal chain, evidence, remediation direction, and residual uncertainty are reported, and the workspace is clean. Say plainly when a cause is probable rather than proven.
When a fix is explicitly requested, hand the proven causal seam to engineer-code-change: add or name a regression check, correct the narrowest cause, rerun the original reproduction and an adjacent negative case, and inspect sibling paths without silently broadening scope.
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.

