agentleFS
Sign inStart free
BurakDBurakD/ai-engineering-harness/skills/root-cause-debug/SKILL.md

root-cause-debug

Skill1 starsChanged 2 months agoApache-2.0View on GitHub

Investigates defects by reproducing or observing the failure, testing hypotheses, identifying the underlying cause, fixing the cause rather than the symptom, and proving the fix with targeted regression evidence.

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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:

    Prefer the smallest coherent change that removes the cause rather than masking an error, suppressing a signal, weakening validation, or …

    line 20
  2. Distinctive:

    Add or strengthen a regression test, invariant, diagnostic check, or reproducible verification when practical.

    line 22
  3. Distinctive:

    Run targeted validation first, followed by broader checks proportional to the potential blast radius and regression risk.

    line 24
  4. Distinctive:

    If repeated high-confidence fixes fail, stop blind iteration.

    line 26
  5. Distinctive:

    Avoid unrelated cleanup while diagnosing the defect unless it is necessary to isolate or safely correct the root cause.

    line 28

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 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 debug

  1. Capture expected behavior, observed behavior, impact, and the smallest reliable reproduction or evidence available.
  2. Confirm that the observed failure is real and identify the conditions under which it appears or disappears.
  3. Inspect relevant recent changes, logs, state transitions, dependencies, configuration, and the actual control or data path before editing.
  4. Form explicit hypotheses about possible causes and gather evidence that can distinguish or falsify them.
  5. Identify the underlying cause, contributing conditions, affected components, and likely blast radius before choosing a fix.
  6. Prefer the smallest coherent change that removes the cause rather than masking an error, suppressing a signal, weakening validation, or special-casing only the observed example.
  7. Add or strengthen a regression test, invariant, diagnostic check, or reproducible verification when practical.
  8. Run targeted validation first, followed by broader checks proportional to the potential blast radius and regression risk.
  9. If repeated high-confidence fixes fail, stop blind iteration. Re-check assumptions, gather new evidence, reconsider the system model, or escalate reasoning rather than repeating the same strategy with more effort.

Avoid unrelated cleanup while diagnosing the defect unless it is necessary to isolate or safely correct the root cause.

Report the root cause, contributing conditions, implemented or proposed fix, regression evidence, affected scope, and remaining uncertainty.

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.

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.

Check your setup, free