| name | spec-driven-rca |
| description | Unified root cause analysis with 4-layer anti-skip enforcement for both tactical (dev workflow diagnosis) and strategic (5 Whys RCA documents) modes. Tactical mode auto-triggers after 2-3 failed fix attempts during TDD, returning fix prescriptions. Strategic mode invoked via /rca command, producing self-contained RCA documents with 5 Whys analysis, evidence collection, and actionable recommendations. Uses Execute-Verify-Record pattern at every step to prevent token optimization bias. Use this skill whenever root cause analysis is needed — after repeated test failures, integration failures, QA violations, framework breakdowns, workflow violations, or when the user runs /rca. Also use when the diagnosis-before-fix rule triggers after 3+ consecutive fix attempts on the same error.
|
| metadata | {"author":"DevForgeAI","version":"2.1.0","category":"quality-assurance","agent-skills-spec-version":"1.0","last-updated":"2026-05-15","migrated-from":"root-cause-diagnosis v1.0.0 + spec-driven-rca v1.0.0"} |
| allowed-tools | ["Read","Glob","Grep","Write","AskUserQuestion","Task","Bash(devforgeai-validate:*)","Bash(git:*)"] |
| model | opus |
| effort | High |
Spec-Driven RCA
Unified root cause analysis for the DevForgeAI framework. Operates in two modes:
- Tactical: Fast diagnosis during dev workflow after repeated fix failures. Returns fix prescriptions. (Phases 00-03)
- Strategic: Full 5 Whys RCA for framework breakdowns. Creates self-contained RCA documents. (Phases 00-02, 04-08)
Core Principle: Understanding WHY a failure occurred is mandatory before attempting HOW to fix it.
If ambiguous or conflicts detected: HALT and use AskUserQuestion
Anti-Skip Enforcement Contract
Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .claude/hooks/ scripts, and .claude/hooks/phase-steps-registry.json (ADR-076).
Validation Modes
This skill operates in two modes, determined during Phase 00 Initialization. Context-marker extraction and mode-detection priority live in references/parameter-extraction.md.
| Mode | When | Phase Route | Output |
|---|
| Tactical | Auto-triggered after 3+ failed fix attempts (diagnosis-before-fix rule). Detected via **Mode:** tactical or **Fix Attempts:** context markers set by /dev. | 00 → 01 → 02 → 03 → END | Fix prescription emitted to tmp/${STORY_ID}/rca-prescription.json for /dev to consume on retry (ADR-074). |
| Strategic | Invoked via /rca command. Detected via **Mode:** strategic, **Issue Description:**, or **Command:** rca markers — or default when no tactical markers present. | 00 → 01 → 02 → 04 → 05 → 06 → 07 → 08 → END | Self-contained RCA document at devforgeai/RCA/RCA-{NNN}-{slug}.md. Phase 08 prompts to invoke github-incident-from-rca. |
If no markers are present after /rca invocation, Phase 00 Step 00.3 disambiguates via AskUserQuestion. The slimmed /rca command sets no context markers itself — the skill derives the issue description from the user's invocation text via references/parameter-extraction.md.
Phase State Initialization [MANDATORY FIRST]
Derive SESSION_ID and the workflow key from mode and context. The workflow key
selects the phase-state schema: tactical is linear 00→01→02→03; strategic genuinely
skips phase 03 (00→01→02→04→05→06→07→08) and is registered as its own key so the
shared sequential gate (to_idx == from_idx+1) makes 02→04 legal by construction
(OBS-1). The ENTIRE run — every phase-init / phase-check / phase-record /
phase-complete call, in this file AND in every phase file — uses --workflow=${WORKFLOW}
(one state file per ${SESSION_ID}-${WORKFLOW}), never a literal:
IF MODE == tactical:
SESSION_ID = "DIAG-" + STORY_ID # Example: "DIAG-STORY-127"
WORKFLOW = "rca" # linear: 00→01→02→03
ELIF MODE == strategic:
SESSION_ID = "RCA-" + rca_number # Example: "RCA-031"
WORKFLOW = "rca-strategic" # skips 03: 00→01→02→04→05→06→07→08
devforgeai-validate phase-init ${SESSION_ID} --workflow=${WORKFLOW} --project-root=.
| Exit Code | Meaning | Action |
|---|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "00". |
| 1 | Existing workflow | Resume. Check checkpoint file for CURRENT_PHASE. |
| 2 | Invalid session ID | HALT. Verify parameters. |
| 127 | CLI not installed | Continue without enforcement (backward compatibility). |
Resume Detection: If resuming, read checkpoint:
Read(file_path="{project-root}/tmp/.rca-checkpoint-${SESSION_ID}.yaml")
Extract current_phase and phase_completion to determine where to resume. In addition to
reading current_phase from this yaml checkpoint,
rehydrate composition_state from tmp/.rca-composition-${SESSION_ID}.json when that
file exists — it is the authoritative
latest merged state (strategic mode, composition phases 04-07). The yaml checkpoint still
supplies current_phase.
Phase Orchestration Loop
FOR phase_num in ACTIVE_PHASES:
phase_id = format(phase_num, "02d")
1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --workflow=${WORKFLOW} --from={prev} --to={phase_id}
IF exit != 0: HALT
2. EXECUTE PHASE:
IF phase_id in {"04", "05", "06", "07"}:
# Strategic-mode composition phase — delegate to the rca-document-composer
# subagent (OPP-8). Do NOT Read/execute the phase file inline here.
# See "Composition Phase Delegation (Phases 04-07)" below for the contract.
Task(subagent_type="rca-document-composer",
description="Compose RCA phase {phase_id}",
prompt=<rendered per Composition Phase Delegation contract>)
Parse the returned JSON envelope.
IF envelope.status != "OK": HALT with envelope.error
# Per-phase composition checkpoint (strategic only; phases 04, 05, 06, 07).
# After EACH composition phase returns, the primary:
# (1) MERGES the returned envelope over the prior checkpoint at
# top-level-key granularity: the envelope wins on key conflicts, and
# any top-level key present in the previous checkpoint but
# absent from the returned envelope is restored from the previous checkpoint.
# (2) Writes the merged state ATOMICALLY (write to a `.tmp` sibling, then rename)
# to `tmp/.rca-composition-${SESSION_ID}.json` (project-scoped per
# operational-safety Rule 2).
# (3) Carries the merged `composition_state` (never the raw return envelope)
# into the next phase.
composition_state = merge_checkpoint(composition_state, envelope.composition_state)
write_atomic("tmp/.rca-composition-${SESSION_ID}.json", composition_state) # .tmp sibling then rename
ELSE:
LOAD: Read(file_path=".claude/skills/spec-driven-rca/phases/{phase_files[phase_id]}")
EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
- Each step's EXECUTE instruction tells you exactly what to do
- Each step's VERIFY instruction tells you how to confirm it happened
- Each step's RECORD instruction tells you what CLI command to call
- The per-step `phase-record --step` calls are run here, inline.
3. RECORD PHASE:
IF phase_id in {"04", "05", "06", "07"}:
# Composition phase: the subagent already ran every per-step
# `phase-record --step=NN.M` call inside the phase file. The primary
# records the delegation itself (--subagent satisfies the CLI, which
# rejects a bare --phase with neither --step nor --subagent):
devforgeai-validate phase-record ${SESSION_ID} --workflow=${WORKFLOW} --phase={phase_id} --subagent=rca-document-composer
ELSE:
# Inline phase: each step recorded itself via its own `--step` call
# during EXECUTE (loop step 2). No additional phase-level record.
4. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=${WORKFLOW} --phase={phase_id} --checkpoint-passed
IF exit != 0: HALT
Composition Phase Delegation (Phases 04-07)
In strategic mode, the four composition phases — 04 (evidence organization), 05 (recommendation generation), 06 (document creation), 07 (validation) — are delegated to the rca-document-composer subagent (OPP-8). Phases 00, 01, 02, 03, 08 run inline in this session; the diagnostic-analyst delegation in Phase 02 is unchanged. Tactical mode never reaches phases 04-07, so this section does not apply to it.
The phase files phases/phase-0{4,5,6,7}-*.md remain the single source of truth — the subagent Read()s and executes them. This skill does not duplicate their steps.
Responsibility split:
| Concern | Owner |
|---|
phase-check entry gate, phase-complete exit gate (loop steps 1, 4) | primary |
Delegation record phase-record --phase=NN --subagent=rca-document-composer (loop step 3) | primary |
Per-step phase-record --step=NN.M calls written in the phase file | rca-document-composer |
| Reading the phase file + executing its EXECUTE-VERIFY-RECORD steps | rca-document-composer |
| Writing / self-healing the RCA document | rca-document-composer |
| Phases 00/01/02/03 and Phase 08 (completion + pipeline) | primary |
composition_state — the accumulating object passed phase-to-phase. Before the loop reaches phase 04, seed it from phases 00/01/02:
composition_state = {
rca_meta: { number, title, date, reporter, component, severity }, # Phase 00
issue: { description, statement }, # Phase 00/01
five_whys: [ {n, question, answer, evidence}, ... 5 entries ], # Phase 02
files_examined: [ {path, lines, finding, excerpt, significance, supports_why}, ... ], # Phase 01
related_rcas: [ {number, title, relationship}, ... ], # Phase 01
diagnostic_analyst: <Phase 02 diagnostic-analyst output, passed through verbatim>, # informational
routing: { involves_workflow, touches_code, touches_rust } # derived from issue + 5 Whys
}
Each delegated phase returns composition_state augmented with its output (04 → evidence, 05 → recommendations, 06 → document_path, 07 → validation_verdict). Merge the returned object over the prior checkpoint per the checkpoint contract above, then pass the merged composition_state into the next phase's Task call. After phase 07, hand the final merged composition_state to Phase 08.
Durability of composition_state (OBS-3). composition_state is checkpointed by the
primary after every composition phase to tmp/.rca-composition-${SESSION_ID}.json with
merge-restore semantics (merge the returned envelope over the prior checkpoint at
top-level-key granularity; write to a .tmp sibling, then rename). A finding therefore
becomes durable at each composition-phase boundary — not only once phase 06 renders the
RCA document. Honest caveat: durability is per-phase — a crash MID-phase loses only
that phase's in-flight augmentation (the last checkpoint, written at the previous phase
boundary, survives). A downstream phase whose return envelope omits a carried top-level
key no longer loses it: the merge restores that key from the previous checkpoint
(any top-level key present in the previous checkpoint but absent from the returned envelope
is restored from the previous checkpoint). On resume, composition_state is rehydrated from
this checkpoint file when it exists.
Task prompt template (loop step 2, composition branch):
When building this prompt the primary MUST serialize the merged composition_state —
the latest checkpoint content (tmp/.rca-composition-${SESSION_ID}.json), never the raw
return envelope of any single phase — into the prompt. This is the channel that carries
restored top-level keys (e.g. a finding a prior phase's envelope omitted) into phase 06's
document.
Task(subagent_type="rca-document-composer",
description="Compose RCA phase {phase_id}",
prompt="""
PHASE: {phase_id}
SESSION_ID: {SESSION_ID}
WORKFLOW: {WORKFLOW} # always "rca-strategic" (composition phases are strategic-only)
composition_state:
{merged composition_state (latest checkpoint) serialized as JSON}
Execute phase {phase_id} per your agent contract: read the phase file, run every
EXECUTE-VERIFY-RECORD step, run the per-step phase-record CLI calls (with
--workflow=${WORKFLOW}), and return the augmented composition_state JSON envelope.
""")
On envelope.status == "BLOCKED": HALT and surface envelope.error. Do NOT retry blind, and do NOT fall back to inline composition — inline fallback would skip the subagent contract and desync the phase-record step registry.
Phase Index
| Phase | Name | Tactical | Strategic | File | Required Subagents |
|---|
| 00 | Initialization | Yes | Yes | phases/phase-00-initialization.md | None |
| 01 | Capture | Yes | Yes | phases/phase-01-capture.md | None |
| 02 | Investigation | Yes | Yes | phases/phase-02-investigation.md | diagnostic-analyst |
| 03 | Prescription | Yes | No | phases/phase-03-prescription.md | None |
| 04 | Evidence Organization | No | Yes | phases/phase-04-evidence-organization.md | rca-document-composer |
| 05 | Recommendation Generation | No | Yes | phases/phase-05-recommendation-generation.md | rca-document-composer |
| 06 | RCA Document Creation | No | Yes | phases/phase-06-document-creation.md | rca-document-composer |
| 07 | Validation & Self-Check | No | Yes | phases/phase-07-validation.md | rca-document-composer |
| 08 | Completion & Pipeline | No | Yes | phases/phase-08-completion.md | None |
HALT: NO FIX ATTEMPTS UNTIL Phase 02 COMPLETES
This is a blocking requirement for BOTH modes. Any code changes, edits, or operations targeting production or test files are FORBIDDEN until the investigation phase produces a report. Violation of this rule constitutes shotgun debugging and invalidates the diagnosis.
If prior fix attempts >= 3 without completing Phase 02, escalate to user:
AskUserQuestion: "{count} fix attempts have failed without diagnosis.
Systematic investigation is required. Proceed with full diagnosis? [Y/n]"
Escalation Protocol (Tactical Mode)
3-Attempt Escalation Rule
| Attempt | Action |
|---|
| 1-2 | Normal fix-test cycle (no diagnosis needed) |
| 3 | HALT. Invoke full spec-driven-rca skill in tactical mode |
| 4 | If diagnosis prescription fails, try next hypothesis |
| 5 | HALT. Escalate to user via AskUserQuestion |
Escalation Message Template
After attempt 5 (or after all hypotheses exhausted):
AskUserQuestion: "Persistent failure after diagnosis and {N} fix attempts.
Error: {error_message}
Diagnosis: {top_hypothesis}
Attempts: {fix_attempt_count}
Options:
1. Provide additional context or hints
2. Skip this acceptance criterion (requires justification)
3. Pause and investigate manually"
State Persistence
Phase State: devforgeai/workflows/${SESSION_ID}-${WORKFLOW}-phase-state.json (tactical: …-rca-…; strategic: …-rca-strategic-…)
Session Memory: .claude/memory/sessions/${SESSION_ID}-rca-session.md
Checkpoint: {project-root}/tmp/.rca-checkpoint-${SESSION_ID}.yaml
Composition Checkpoint: tmp/.rca-composition-${SESSION_ID}.json (strategic mode, composition phases 04-07; merged envelope; rehydrated on resume)
Reference Files (Progressive Loading)
References are loaded on-demand by each phase. Do NOT pre-load all references.
| Phase | Reference File | Purpose |
|---|
| 00 | references/parameter-extraction.md | Context marker extraction for both modes |
| 01 (strategic) | references/framework-integration-points.md | Determine which files to read |
| 02 (tactical) | references/investigation-patterns.md | 6 failure category taxonomy |
| 02 (strategic) | references/5-whys-methodology.md | How to perform effective 5 Whys |
| 04 | references/evidence-collection-guide.md | Evidence quality criteria |
| 05 | references/recommendation-framework.md | Priority criteria, implementation details |
| 05 | references/recommendation-contract.md | Tiered field contract for downstream consumers (ADR-074) |
| 06 | references/rca-writing-guide.md | RCA document standards |
| — | references/workflow-integration.md | Dev workflow integration hooks (external consumers) |
| — | references/rca-help.md | Command help and examples |
Asset Templates (Strategic Mode)
| Asset | Purpose |
|---|
assets/5-whys-template.md | 5 Whys section template for RCA document |
assets/evidence-section-template.md | Evidence organization template |
assets/rca-document-template.md | Full RCA document template |
assets/recommendation-template.md | Recommendation subsection template |
Integration with DevForgeAI Framework
Iteration Log as Evidence Source
The iteration log is an evidence source for RCA analysis, alongside the story file, test output, and code diff. During Phase 01 (Capture) evidence gathering, read the iteration log to extract cycle timeline evidence:
devforgeai-validate iteration-log-status ${STORY_ID} --format=json
Cycle Timeline Evidence:
- Each cycle's
dev.approach_summary documents what was tried
- Each cycle's
qa.blocking_issues documents what failed and why
- The combination of approach_summary and blocking_issues across cycles forms a timeline of evidence showing the progression of the issue
Hypothesis Generation from Spinning Wheels:
spinning_wheels.repeated_root_causes directly informs "Why #1" hypothesis generation- If the same root cause appears across multiple cycles, it should be the primary hypothesis
- repeated_root_causes provides pre-analyzed data that accelerates the 5 Whys process
Graceful Degradation:
- If the iteration log is missing or unavailable: proceed with standard evidence gathering (story file, test output, code diff) without timeline data
Invoked By
Commands:
/rca slash command (strategic mode, primary invocation)
Automatic Triggers (tactical mode):
diagnosis-before-fix rule after 3+ failed fix attempts- spec-driven-dev Phase 03 (Green) after 2+ test failures
- spec-driven-dev Phase 05 (Integration) on non-environment failures
- spec-driven-qa Phase 02 (Deep Analysis) on CRITICAL/HIGH violations
Manual Invocation:
**Mode:** tactical
**Story ID:** STORY-NNN
**Error:** {error message}
**Fix Attempts:** {count}
Skill(command="spec-driven-rca")
Subagents
| Subagent | Role | Phase | Required |
|---|
| diagnostic-analyst | Read-only spec drift detection against 6 context files | Phase 02 | Yes (both modes) |
| rca-document-composer | Composes the RCA document — reads & executes phases 04-07; owns per-step phase-record calls; writes the RCA document | Phases 04-07 | Yes (strategic mode) |
Related Skills
- spec-driven-dev (triggers tactical mode on test failures; consumes
rca-prescription.json on Phase 03 retry per ADR-074)
- spec-driven-qa (triggers tactical mode on validation failures)
- spec-driven-stories (consumes RCA recommendations via /create-stories-from-rca per
references/recommendation-contract.md)
- github-incident-from-rca (Phase 08 hand-off — strategic-mode completion offers to invoke for GitHub issue creation; sole
gh issue create site)
Workflow Completion Validation
IF MODE == tactical:
IF completed_phases < 4: HALT "WORKFLOW INCOMPLETE - {count}/4 phases"
IF completed_phases == 4: "Tactical diagnosis complete - returning prescription"
IF MODE == strategic:
IF completed_phases < 8: HALT "WORKFLOW INCOMPLETE - {count}/8 phases"
IF completed_phases == 8: "Strategic RCA complete - document created"
Success Criteria
Tactical Mode
Strategic Mode
Change Log
| Version | Date | Change |
|---|
| 2.0.0 | 2026-03-18 | Initial creation. Merged root-cause-diagnosis v1.0.0 (tactical 4-phase) and spec-driven-rca v1.0.0 (strategic 8-phase) into unified spec-driven skill with Execute-Verify-Record anti-skip enforcement. |
| 2.1.0 | 2026-05-15 | OPP-8: strategic-mode composition phases 04-07 delegated to the new rca-document-composer subagent. Phase Orchestration Loop dispatches 04-07 via Task(); primary retains phase-boundary gates, phase-level phase-record, and Phase 08. Phase files 04-07 unchanged (Option C). Added "Composition Phase Delegation" section. |
| 2.2.0 | 2026-05-20 | ADR-074 modernization: slimmed /rca to ≤25 lines (Orchestration Thinness Invariant); collapsed Execution Model Self-Check into hook-backed enforcement (3 new hooks: pre-rca-recommendation-write.sh, pre-rca-document-write.sh, pre-rca-prescription-write.sh); collapsed Validation Modes prose into 2-row table referencing parameter-extraction.md; published references/recommendation-contract.md (tiered Required/Rendered/Context contract); Phase 03 now emits tmp/${STORY_ID}/rca-prescription.json for /dev to consume on retry; Phase 08 offers github-incident-from-rca hand-off. SKILL.md 475 → ~408 lines. |
