root-cause-investigator
Skill19 starsChanged 50 days agoMITView on GitHub
Investigate software defects and unexpected behaviour using read-only evidence before remediation. Use when the user asks to diagnose, find a root cause, explain a failure, or trace a UI, API, service, data, configuration, or test problem; do not use for implementing an already-established fix or for a general code review.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- future-mine/claude-skilltheir own version, first seen Oct 8, 2026
- artaasd95/SLM-skillstheir own version, first seen Jul 26, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- future-mine/claude-skill★ 1same name
- artaasd95/SLM-skills★ 0same name
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.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- content-brief-gap-investigatorSkill
- content-draft-assistantSkill
- content-publish-readiness-checklistSkill
- feature-launch-readiness-checklistSkill
- prd-draft-assistantSkill
- requirements-gap-investigatorSkill
- post-performance-investigatorSkill
- social-caption-drafterSkill
- social-publish-readiness-checklistSkill
- changelog-entry-drafterSkill
- pre-merge-readiness-checklistSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 17 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
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
Treat the task as diagnosis-only by default.
- Distinctive: line 13
Do not edit files, install or upgrade dependencies, restart services, run migrations, delete data, change configuration, or mutate external …
- Distinctive: line 14
Use read-only inspection and non-destructive diagnostics available in the host environment.
- Distinctive: line 15
Before running a check that may create files, alter state, incur material cost, expose data, or affect a shared or production system, …
- Distinctive: line 16
Never treat access to a tool as permission to use it beyond the user's request.
- Distinctive: line 19
If the user explicitly includes remediation in the same request, finish and report the diagnosis first.
- Distinctive: line 30
when the problem occurs and whether it is reproducible.
- Distinctive: line 33
Ask only for missing information that prevents a useful investigation.
- Distinctive: line 44
Unknown: not established with the available access or evidence.
- Distinctive: line 56
Follow actual identifiers, field names, values, and control-flow branches across boundaries.
- Distinctive: line 69
Prefer discriminating checks over collecting more evidence that would be consistent with every hypothesis.
- Distinctive: line 73
Do not label the nearest visible failure as the root cause without tracing why it occurred.
- Distinctive: line 97
Stop after the report. Do not silently begin remediation.
- Distinctive: line 101
Stop and explain the boundary when:
- Distinctive: line 109
When blocked by missing evidence, name the specific evidence needed and the smallest next check that could obtain it.
- Distinctive: line 113
Before returning the report, confirm that:
- Distinctive: line 119
no change is described as completed unless it was authorised and verified.
≈ “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
Root Cause Investigator
Determine the most defensible cause of the reported software problem. Produce an evidence-backed diagnosis and stop before remediation unless the user separately authorises changes.
Operating boundary
- Treat the task as diagnosis-only by default.
- Do not edit files, install or upgrade dependencies, restart services, run migrations, delete data, change configuration, or mutate external systems.
- Use read-only inspection and non-destructive diagnostics available in the host environment.
- Before running a check that may create files, alter state, incur material cost, expose data, or affect a shared or production system, explain the need and obtain permission.
- Never treat access to a tool as permission to use it beyond the user's request.
- Redact secrets and minimise personal or production data in the report.
If the user explicitly includes remediation in the same request, finish and report the diagnosis first. Make the transition from diagnosis to remediation visible, preserve the established scope, and follow the host's approval requirements.
Investigation workflow
1. Frame the problem
Record:
- the reported symptom;
- the expected behaviour;
- the affected environment and scope;
- when the problem occurs and whether it is reproducible; and
- relevant recent changes, if known.
Ask only for missing information that prevents a useful investigation. Do not convert unverified user statements into observed facts.
2. Establish observations
Inspect the narrowest relevant evidence first. Depending on the problem, this may include source paths, tests, logs, error messages, requests and responses, configuration names, schemas, recent diffs, or runtime status.
For every important claim, distinguish among:
- Observed: directly verified during this investigation.
- Reported: supplied by the user or an external source but not independently verified.
- Inferred: a conclusion drawn from other evidence.
- Unknown: not established with the available access or evidence.
State validation limits precisely. Reading code does not prove runtime behaviour; a passing unit test does not prove a live integration; a response sample does not prove all environments behave identically.
3. Trace the system path
Map the shortest end-to-end path capable of producing the symptom. For example:
user action -> UI state -> request -> API handler -> service -> data source -> response mapping -> rendered resultFollow actual identifiers, field names, values, and control-flow branches across boundaries. Identify the earliest point where actual behaviour diverges from expected behaviour.
4. Compare hypotheses
List the plausible causes supported by the current evidence. Include alternatives when more than one explanation remains credible.
For each hypothesis, record:
- evidence supporting it;
- evidence contradicting it;
- the smallest safe check that would distinguish it from alternatives; and
- its current status: supported, weakened, rejected, or untested.
Prefer discriminating checks over collecting more evidence that would be consistent with every hypothesis.
5. Establish the causal chain
Do not label the nearest visible failure as the root cause without tracing why it occurred. Separate:
- Symptom: what the user or system experiences.
- Failure point: where behaviour first becomes incorrect.
- Root cause: the underlying condition that produced the failure point.
- Contributing factors: conditions that increased likelihood or reduced detection.
A root-cause statement should explain the mechanism connecting cause to symptom and cite the supporting evidence. If that mechanism cannot be established, report the investigation as inconclusive rather than guessing.
6. Report and stop
For a small investigation, report the diagnosis directly. For a substantial or ambiguous investigation, use references/investigation-report.md.
Include:
- investigation status;
- root cause or leading hypothesis;
- confidence and why;
- causal chain;
- key evidence and its source;
- rejected or unresolved alternatives;
- validation limits; and
- recommended next step, clearly labelled as not yet performed.
Stop after the report. Do not silently begin remediation.
Stopping conditions
Stop and explain the boundary when:
- the root cause is established well enough to answer the request;
- available evidence cannot distinguish the remaining hypotheses;
- the next useful check requires credentials, permissions, destructive actions, production access, or broader scope;
- evidence suggests a security incident, data loss, or safety risk requiring the user's incident process; or
- the requested evidence is unavailable in the current environment.
When blocked by missing evidence, name the specific evidence needed and the smallest next check that could obtain it.
Quality check
Before returning the report, confirm that:
- the conclusion explains the symptom rather than merely restating it;
- important claims are labelled observed, reported, inferred, or unknown;
- plausible alternatives were tested or remain explicitly unresolved;
- confidence matches the strength of the evidence;
- no change is described as completed unless it was authorised and verified; and
- the response separates diagnosis from any proposed remediation.
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.

