agentleFS
S3n0001S3n0001/agent-skills/diagnose-root-causes/SKILL.md

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).

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

    Read the repository instructions.

    line 12
  2. Distinctive:

    If reproduction is unsafe or impossible, work from logs, traces, state, and history, and label every conclusion by the strength of its …

    line 15
  3. Distinctive:

    Keep a short ledger and update it as you go:

    line 21
  4. Distinctive:

    Never declare a cause after merely swallowing an error, adding a fallback, raising a timeout or retry count, clearing state, weakening a …

    line 33
  5. Distinctive:

    Keep experiments reversible and isolated.

    line 35
  6. Distinctive:

    When a fix is explicitly requested, hand the proven causal seam to engineer-code-change: add or name a regression check, correct the …

    line 47

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

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

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

  1. Read the repository instructions. Write down actual versus expected behavior, the triggering input, environment, version, timing, frequency, and last known good state.
  2. Build the smallest faithful, safe reproduction through the real entry point or its closest substitute. Keep the exact command, request, fixture, interaction, and output.
  3. Classify the symptom: deterministic, intermittent, environment-specific, or pre-existing baseline behavior.
  4. 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.

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.