Add evidence-driven root cause analysis skill

[byapparov]

Closes #25

Summary

• add a portable, read-only-by-default root cause analysis skill
• include a report template and causal quality gate for evidence-backed causal branches and prevention work
• register the skill in the public catalog and add a behavioral eval

Verification

• python3 /home/bulat/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/root-cause-analysis
• npm test (27 passed)
• npm run validate (13 public skills)

Risk

Documentation-only public skill. It explicitly separates active mitigation from RCA and requires authorization for external actions.

[aictrl-dev]

Code review

Verdict: Looks good. ✅ · 0 findings

Reviewed 9 files · 0 inline · view all 0 findings ↗

---

aictrl · AI code review for fast-moving teams · aictrl.dev

[aictrl-dev]

🟡 Template has no 'consequence' classification slot.

🤖 Fix with your agent

Fix this code review finding (aictrl-dev/skills PR #26, skills/root-cause-analysis/reference/rca-template.md:49-59):

Problem: Template has no 'consequence' classification slot
Detail: SKILL.md (line 78) instructs the analyst to "Classify each conclusion as a root systemic cause, contributing condition, trigger, failed/missing safeguard, consequence, or unresolved hypothesis." The report template's "Causal classification" section (rca-template.md:49-59) only provides headings for five of those six buckets — "Root systemic causes", "Contributing conditions, triggers, and missing safeguards", and "Unresolved hypotheses" — with no slot for "consequence". A conclusion classified as a consequence (a downstream effect rather than itself a cause) has no home in the report, so the workflow's own classify step emits a category the template cannot capture. Either add a "### Consequences" subsection (or point readers to the existing "Impact and violated invariant" section) or drop "consequence" from the SKILL.md enumeration so the two stay in contract.
Suggested fix: Either add a "### Consequences" subsection in the Causal classification section (e.g. "- `<cause ID>` — `<downstream effect and why it is an effect, not a cause>`"), or remove "consequence" from the classify list in SKILL.md:78 since consequences are already captured under "Impact and violated invariant".

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.

Why this matters

SKILL.md (line 78) instructs the analyst to "Classify each conclusion as a root systemic cause, contributing condition, trigger, failed/missing safeguard, consequence, or unresolved hypothesis." The report template's "Causal classification" section (rca-template.md:49-59) only provides headings for five of those six buckets — "Root systemic causes", "Contributing conditions, triggers, and missing safeguards", and "Unresolved hypotheses" — with no slot for "consequence". A conclusion classified as a consequence (a downstream effect rather than itself a cause) has no home in the report, so the workflow's own classify step emits a category the template cannot capture. Either add a "### Consequences" subsection (or point readers to the existing "Impact and violated invariant" section) or drop "consequence" from the SKILL.md enumeration so the two stay in contract.

## Causal classification

### Root systemic causes

- `<cause ID>` — `<cause statement and why it qualifies>`

### Contributing conditions, triggers, and missing safeguards

- `<cause ID or trigger>` — `<condition>`

### Unresolved hypotheses

[aictrl-dev]

🟡 Template heading drops 'failed' from safeguards.

--- a/skills/root-cause-analysis/reference/rca-template.md
+++ b/skills/root-cause-analysis/reference/rca-template.md
@@ -55,1 +55,1 @@
-### Contributing conditions, triggers, and missing safeguards
+### Contributing conditions, triggers, and failed or missing safeguards

🤖 Fix with your agent

Fix this code review finding (aictrl-dev/skills PR #26, skills/root-cause-analysis/reference/rca-template.md:55):

Problem: Template heading drops 'failed' from safeguards
Detail: SKILL.md (line 78) enumerates "failed/missing safeguard" as a distinct classification, deliberately separating a safeguard that existed but failed (an alert that didn't fire, a check that ran but didn't block) from one that was simply absent. The corresponding template heading (rca-template.md:55) reads only "Contributing conditions, triggers, and missing safeguards" — it drops "failed". A failed-but-present safeguard would be misfiled under "missing", losing the failed-vs-missing distinction the workflow deliberately draws. Rename the heading to mirror the SKILL.md enumeration.
Suggested fix: Rename the heading at rca-template.md:55 from "Contributing conditions, triggers, and missing safeguards" to "Contributing conditions, triggers, and failed or missing safeguards" to match SKILL.md's "failed/missing safeguard" enumeration.

Suggested patch:
--- a/skills/root-cause-analysis/reference/rca-template.md
+++ b/skills/root-cause-analysis/reference/rca-template.md
@@ -55,1 +55,1 @@
-### Contributing conditions, triggers, and missing safeguards
+### Contributing conditions, triggers, and failed or missing safeguards


Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.

Why this matters

SKILL.md (line 78) enumerates "failed/missing safeguard" as a distinct classification, deliberately separating a safeguard that existed but failed (an alert that didn't fire, a check that ran but didn't block) from one that was simply absent. The corresponding template heading (rca-template.md:55) reads only "Contributing conditions, triggers, and missing safeguards" — it drops "failed". A failed-but-present safeguard would be misfiled under "missing", losing the failed-vs-missing distinction the workflow deliberately draws. Rename the heading to mirror the SKILL.md enumeration.

### Contributing conditions, triggers, and missing safeguards

- `<cause ID or trigger>` — `<condition>`

[aictrl-dev]

Code review

Verdict: Looks good — only minor / nit comments below. · 🔴 0 · 🟠 0 · 🟡 2 · ⚪ 0 · 0/2 resolved

• 🟡 skills/root-cause-analysis/reference/rca-template.md:49-59 — Template has no 'consequence' classification slot
• 🟡 skills/root-cause-analysis/reference/rca-template.md:55 — Template heading drops 'failed' from safeguards

🤖 Fix all 2 open findings with your agent

Fix the following code review findings on aictrl-dev/skills PR #26 (head branch).
Run the relevant tests/linters after each change.

1. skills/root-cause-analysis/reference/rca-template.md:49-59 — Template has no 'consequence' classification slot
   Detail: SKILL.md (line 78) instructs the analyst to "Classify each conclusion as a root systemic cause, contributing condition, trigger, failed/missing safeguard, consequence, or unresolved hypothesis." The report template's "Causal classification" section (rca-template.md:49-59) only provides headings for five of those six buckets — "Root systemic causes", "Contributing conditions, triggers, and missing safeguards", and "Unresolved hypotheses" — with no slot for "consequence". A conclusion classified as a consequence (a downstream effect rather than itself a cause) has no home in the report, so the workflow's own classify step emits a category the template cannot capture. Either add a "### Consequences" subsection (or point readers to the existing "Impact and violated invariant" section) or drop "consequence" from the SKILL.md enumeration so the two stay in contract.
   Suggested fix: Either add a "### Consequences" subsection in the Causal classification section (e.g. "- `<cause ID>` — `<downstream effect and why it is an effect, not a cause>`"), or remove "consequence" from the classify list in SKILL.md:78 since consequences are already captured under "Impact and violated invariant".
2. skills/root-cause-analysis/reference/rca-template.md:55 — Template heading drops 'failed' from safeguards
   Detail: SKILL.md (line 78) enumerates "failed/missing safeguard" as a distinct classification, deliberately separating a safeguard that existed but failed (an alert that didn't fire, a check that ran but didn't block) from one that was simply absent. The corresponding template heading (rca-template.md:55) reads only "Contributing conditions, triggers, and missing safeguards" — it drops "failed". A failed-but-present safeguard would be misfiled under "missing", losing the failed-vs-missing distinction the workflow deliberately draws. Rename the heading to mirror the SKILL.md enumeration.
   Suggested fix: Rename the heading at rca-template.md:55 from "Contributing conditions, triggers, and missing safeguards" to "Contributing conditions, triggers, and failed or missing safeguards" to match SKILL.md's "failed/missing safeguard" enumeration.

📋 Out-of-diff findings (2)

Sev	Location	Finding
🟡	skills/root-cause-analysis/reference/rca-template.md:49-59	Template has no 'consequence' classification slot
🟡	skills/root-cause-analysis/reference/rca-template.md:55	Template heading drops 'failed' from safeguards

Reviewed 9 files · 0 inline · view all 2 findings ↗

---

aictrl · AI code review for fast-moving teams · aictrl.dev

[aictrl-dev]

⚪ Curly quotes inconsistent with bundle style.

🤖 Fix with your agent

Fix this code review finding (aictrl-dev/skills PR #26, skills/root-cause-analysis/reference/causal-quality-gate.md:47-48):

Problem: Curly quotes inconsistent with bundle style
Detail: Line 47 uses Unicode curly quotes (“contributed to,” “made possible,” “failed to contain”) while every other quoted phrase across the three new files (and the rest of the skill bundle) uses straight ASCII quotes (e.g. the Avoid list in SKILL.md and the Shallow-analysis table in this same file). No functional impact — markdown renders both — but it is a stylistic inconsistency likely introduced by a smart-quotes editor.
Suggested fix: Replace the curly quotes with straight ASCII quotes: Prefer "contributed to," "made possible," or "failed to contain" when the ...

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.

Why this matters

Line 47 uses Unicode curly quotes (“contributed to,” “made possible,” “failed to contain”) while every other quoted phrase across the three new files (and the rest of the skill bundle) uses straight ASCII quotes (e.g. the Avoid list in SKILL.md and the Shallow-analysis table in this same file). No functional impact — markdown renders both — but it is a stylistic inconsistency likely introduced by a smart-quotes editor.

5. Who can change it, through what mechanism?
6. What evidence could strengthen or falsify it?

Prefer “contributed to,” “made possible,” or “failed to contain” when the
evidence does not support necessary or sufficient causality.

## Initiative quality checks

[aictrl-dev]

Code review

Verdict: Looks good — only minor / nit comments below. · 🔴 0 · 🟠 0 · 🟡 0 · ⚪ 1 · 0/1 resolved

• ⚪ skills/root-cause-analysis/reference/causal-quality-gate.md:47-48 — Curly quotes inconsistent with bundle style

🤖 Fix all 1 open findings with your agent

Fix the following code review findings on aictrl-dev/skills PR #26 (head branch).
Run the relevant tests/linters after each change.

1. skills/root-cause-analysis/reference/causal-quality-gate.md:47-48 — Curly quotes inconsistent with bundle style
   Detail: Line 47 uses Unicode curly quotes (“contributed to,” “made possible,” “failed to contain”) while every other quoted phrase across the three new files (and the rest of the skill bundle) uses straight ASCII quotes (e.g. the Avoid list in SKILL.md and the Shallow-analysis table in this same file). No functional impact — markdown renders both — but it is a stylistic inconsistency likely introduced by a smart-quotes editor.
   Suggested fix: Replace the curly quotes with straight ASCII quotes: Prefer "contributed to," "made possible," or "failed to contain" when the ...

📋 Out-of-diff findings (1)

Sev	Location	Finding
⚪	skills/root-cause-analysis/reference/causal-quality-gate.md:47-48	Curly quotes inconsistent with bundle style

Reviewed 9 files · 0 inline · view all 1 findings ↗

---

aictrl · AI code review for fast-moving teams · aictrl.dev