diff --git a/submissions/root-cause-analysis/README.md b/submissions/root-cause-analysis/README.md new file mode 100644 index 00000000..06c677cd --- /dev/null +++ b/submissions/root-cause-analysis/README.md @@ -0,0 +1,38 @@ +# Root Cause Analysis + +Use this skill when you need to understand why something failed — not just what went wrong, but the underlying cause you can act on. + +## What it does + +Root Cause Analysis (RCA) turns incident symptoms into a clear diagnosis using structured techniques: + +- **5 Whys** — keep asking "why" until you reach a fixable origin. +- **Fishbone diagram** — map causes across six categories: People, Process, Technology, Data, Environment, Management. + +The skill distinguishes between a **root cause** (the fundamental origin) and **contributing factors** (things that made the problem worse). That distinction changes what you fix and whether the problem stays fixed. + +## When to use it + +- An incident, defect, or outage happened and you need to know why. +- You are preparing a post-mortem or incident review. +- A process keeps failing in the same place and surface fixes are not working. +- You want to separate "what happened" from "what actually caused it." + +## What you get + +- A clear root cause statement. +- The evidence chain behind it. +- A list of contributing factors. +- Recommended actions, ordered by whether they address the root cause or only contributing factors. + +## What you need + +- A clear symptom or failure to investigate. +- Access to the person or system that observed the problem. +- Any available logs, timelines, or context that show what happened. + +## Tips + +- Start with a precise problem statement. "The service went down" is a symptom; "the payment API returned 503 for 12 minutes during the 9 AM traffic spike" is a problem statement. +- Keep asking "why" at least three levels before proposing causes. +- Contributing factors are still useful to document — they reduce recurrence even if they are not the root cause. diff --git a/submissions/root-cause-analysis/SKILL.md b/submissions/root-cause-analysis/SKILL.md new file mode 100644 index 00000000..359326e2 --- /dev/null +++ b/submissions/root-cause-analysis/SKILL.md @@ -0,0 +1,54 @@ +--- +name: root-cause-analysis +description: Use this skill whenever the user asks to diagnose why something failed, find the root cause of an incident, conduct a post-mortem, analyze a problem or defect, distinguish symptoms from causes, or apply 5 Whys or Fishbone analysis. Trigger on phrases like "why did this happen", "root cause", "post-mortem", "5 whys", "fishbone", "what caused this", "diagnose the failure", "why did it fail", "underlying cause". Do NOT trigger for general problem solving (use business-os), refining existing plans (use idea-refiner), or content quality audits (use content-quality-auditor). +--- + +# Root Cause Analysis + +Guide the user through structured problem diagnosis to move from observed symptoms to the true underlying cause, using repeatable techniques that prevent guessing or stopping at surface-level fixes. + +## Instructions + +1. **Lock the problem statement** + - State the exact symptom or failure in one sentence. + - Capture when it occurred, where, and who or what was affected. + - Do not allow vague wording like "it broke" or "performance is bad." + +2. **Map the symptom chain** + - List every observed symptom as a fact, not a hypothesis. + - For each symptom, ask: "What could produce this?" + - Keep asking "why" at least three levels deep before proposing any cause. + +3. **Apply 5 Whys** + - Start from the problem statement. + - Ask "why" repeatedly, recording each answer. + - Stop when you reach a cause that, if fixed, would prevent the symptom from recurring. + - If you reach a cause that is a contributing factor rather than a fixable origin, keep going. + - Load `references/rca-methods.md` if the problem is complex or the user asks for a specific technique. + +4. **Build a Fishbone diagram** + - Categorize potential causes across: People, Process, Technology, Data, Environment, Management. + - For each category, list specific contributing factors backed by evidence the user can confirm. + - Do not invent facts; if a factor is uncertain, mark it as unverified. + - Use `assets/fishbone-template.html` to structure the diagram. Open the template, replace the placeholder text in each category branch with the contributing factors identified above, and return the filled-in HTML so the user can save and open it. + - Do NOT build a new diagram from scratch. Do NOT generate matplotlib, code-generated plots, or any output that is not based on the provided template. Editing and returning the provided HTML template is the correct output. + +5. **Separate root cause from contributing factors** + - Root cause: the fundamental origin that, if eliminated, prevents recurrence. + - Contributing factor: made the problem more likely or more severe, but is not the origin. + - Present both clearly; fixing only contributing factors will not fully resolve the issue. + +6. **Output the diagnosis** + - Root cause: one precise sentence. + - Evidence: the "why" chain or diagram nodes that support it. + - Contributing factors: bullet list with severity or likelihood. + - Recommended actions: ordered by whether they address the root cause or only contributing factors. + +## Guardrails + +- Never skip the "why" chain. Symptoms are not causes. +- Do not propose fixes before the root cause is stated. +- Separate factual evidence from assumptions; label anything unverified. +- If evidence is missing, say so explicitly rather than inferring. +- Do not assign blame. Describe mechanisms and conditions, not people. +- Stop at actionable causes. Do not drift into speculation or philosophy. diff --git a/submissions/root-cause-analysis/assets/fishbone-template.html b/submissions/root-cause-analysis/assets/fishbone-template.html new file mode 100644 index 00000000..03a2bf93 --- /dev/null +++ b/submissions/root-cause-analysis/assets/fishbone-template.html @@ -0,0 +1,134 @@ + + + + + +Fishbone Diagram Template + + + +

Fishbone Diagram Template

+
PROBLEM STATEMENT
+ +
+ + +
+
People
skills, training, staffing
+
Process
steps, policies, approvals
+
Technology
tools, infra, config
+
+ +
+
+
+
+ +
+
Data
quality, completeness
+
Environment
external conditions
+
Management
priorities, resources
+
+
+ +
+
+ +
+ + + + \ No newline at end of file diff --git a/submissions/root-cause-analysis/metadata.json b/submissions/root-cause-analysis/metadata.json new file mode 100644 index 00000000..1a2ac71a --- /dev/null +++ b/submissions/root-cause-analysis/metadata.json @@ -0,0 +1,11 @@ +{ + "name": "Root Cause Analysis", + "description": "Diagnose the true cause of a problem — not just its symptoms — using structured techniques like 5 Whys, Fishbone diagrams, and contributing factor analysis.", + "platforms": ["Cowork", "Copilot Studio", "Scout"], + "tags": ["problem-solving", "analysis", "decision-making", "investigation", "debugging"], + "author": "Nayananshu Garai", + "authorUrl": "https://github.com/N-Garai", + "version": "1.0.0", + "createdAt": "2026-08-04", + "updatedAt": "2026-08-04" +} diff --git a/submissions/root-cause-analysis/references/rca-methods.md b/submissions/root-cause-analysis/references/rca-methods.md new file mode 100644 index 00000000..61a79a5a --- /dev/null +++ b/submissions/root-cause-analysis/references/rca-methods.md @@ -0,0 +1,60 @@ +# RCA Techniques Reference + +Load this file when the user wants deeper guidance on a specific technique, or when the problem is complex enough that a single-pass analysis is not sufficient. + +## 5 Whys + +Starting from the problem statement, ask "why" repeatedly. Each answer becomes the next question. + +**Rules:** +- Ask "why" at least three times before stopping. Most root causes are found between 3 and 5 levels. +- Each answer must be factual. If you do not know, say so and ask the user. +- Stop when you reach a cause that, if fixed, would prevent the symptom from recurring. +- If you reach a person's name rather than a process or system condition, you have stopped too early. Keep going until you reach a mechanism. + +**Example chain:** +1. Why did the deploy fail? The build step returned 500. +2. Why did the build step return 500? The linter crashed on a missing config file. +3. Why was the config file missing? The bootstrap script skips it when the environment variable is absent. +4. Why is the environment variable absent in CI? The pipeline template was not updated when the config was moved. + +Root cause: the pipeline template was not updated when the config was moved. + +## Fishbone Diagram (Ishikawa) + +Categorize causes across six standard categories. For each category, list specific contributing factors. + +**Categories:** +- **People** — skills, training, staffing, communication, handoffs. +- **Process** — steps, policies, approvals, dependencies, sequencing. +- **Technology** — tools, infrastructure, integrations, capacity, configuration. +- **Data** — quality, completeness, freshness, schema, access. +- **Environment** — external conditions, market, regulations, physical constraints. +- **Management** — priorities, resources, decisions, risk tolerance, oversight. + +**Rules:** +- List causes, not fixes. The diagram is diagnostic, not prescriptive. +- Each item should be specific enough to verify. "Bad communication" is vague; "the handoff doc was not updated after the migration" is specific. +- Mark items as confirmed, unverified, or disproven. Do not present guesses as facts. + +## Contributing Factors vs Root Cause + +A **root cause** is the fundamental origin. Eliminate it and the problem does not recur. + +A **contributing factor** increases the likelihood or severity of the problem, but is not the origin. Eliminate it and the problem can still happen. + +**Example:** +- Symptom: server crashed. +- Root cause: the memory leak was never fixed because the monitoring alert was disabled. +- Contributing factors: traffic was 3x normal, the instance type was undersized, the deploy happened at peak load. + +Fixing the instance size or deferring the deploy reduces the chance of another crash, but the memory leak will eventually cause another one. Fix the root cause first. + +## Output Format + +When presenting the diagnosis: + +1. **Root cause** — one sentence. +2. **Evidence** — the why-chain nodes or fishbone entries that support it. +3. **Contributing factors** — bullet list with estimated impact or likelihood. +4. **Recommended actions** — ordered by whether they address the root cause or only contributing factors.