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. Every step in this skill exists because a previous failure proved it necessary.

If ambiguous or conflicts detected: HALT and use AskUserQuestion

Execution Model

This skill expands inline. After invocation, execute Phase State Initialization immediately. Do not wait passively, ask permission, or offer execution options.

Self-Check (if ANY box is true = VIOLATION):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively for results
• Asking "should I execute this?"
• Skipping a phase because it "seems simple"
• Combining multiple phases into one
• Summarizing instead of loading a reference file
• Skipping verification because "I already know the answer"
• Attempting fixes before Phase 02 Investigation completes
• Guessing at root causes without evidence

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase State Initialization now.

Anti-Skip Enforcement Contract

This skill enforces 4 independent anti-skip layers. ALL FOUR must fail for a step to be skipped:

1. Fresh-context subagent execution — diagnostic-analyst subagent in Phase 02 runs in isolated read-only context, preventing accidental state mutation during investigation
2. Binary CLI gates — devforgeai-validate commands enforce phase state transitions; cannot be forged by LLM
3. Hook enforcement — Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification — Glob/Grep confirmation after every step, not trust-based

Execute-Verify-Record Pattern: Every mandatory step in every phase file has three parts:

• EXECUTE: The exact action to perform
• VERIFY: How to confirm the action happened (Glob, Grep, exit code)
• RECORD: CLI command to record completion (devforgeai-validate phase-record)

Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary.

Validation Modes

This skill operates in two modes, determined during Phase 00 Initialization.

Tactical Mode (Dev Workflow Diagnosis)

When: Auto-triggered during dev workflow after 2-3 failed fix attempts on the same error. Also triggered when diagnosis-before-fix rule fires.

Phase Route: 00 → 01 → 02 → 03 → END

Output: Fix prescriptions returned to invoking workflow phase for execution.

Context Markers (set by dev workflow):

• **Mode:** tactical
• **Fix Attempts:** {count}
• **Phase:** {Green|Integration|QA}
• **Story ID:** {STORY-NNN}
• **Error:** {error message}

Strategic Mode (Full RCA Document)

When: Invoked via /rca command or manually for framework breakdowns.

Phase Route: 00 → 01 → 02 → 04 → 05 → 06 → 07 → 08 → END

Output: Self-contained RCA document in devforgeai/RCA/RCA-{NNN}-{slug}.md

Context Markers (set by /rca command):

• **Mode:** strategic (or absent — defaults to strategic)
• **Issue Description:** {text}
• **Severity:** {CRITICAL|HIGH|MEDIUM|LOW|infer}
• **Command:** rca

Mode Detection Priority

IF context contains "**Mode:** tactical" OR "**Fix Attempts:**":
    MODE = tactical
    ACTIVE_PHASES = [00, 01, 02, 03]
ELIF context contains "**Mode:** strategic" OR "**Issue Description:**" OR "**Command:** rca":
    MODE = strategic
    ACTIVE_PHASES = [00, 01, 02, 04, 05, 06, 07, 08]
ELSE:
    AskUserQuestion:
        Question: "This skill supports two modes. Which do you need?"
        Header: "RCA Mode"
        Options:
            - label: "Tactical — Quick diagnosis for dev workflow failures"
              description: "Returns fix prescriptions. Use when tests keep failing during /dev."
            - label: "Strategic — Full RCA with 5 Whys analysis"
              description: "Creates self-contained RCA document. Use for framework breakdowns."
        multiSelect: false
    MODE = user selection
    ACTIVE_PHASES = tactical ? [00,01,02,03] : [00,01,02,04,05,06,07,08]

Parameter Extraction

Extract parameters from conversation context markers. See references/parameter-extraction.md for the complete extraction algorithm for both modes.

Phase State Initialization [MANDATORY FIRST]

Derive SESSION_ID from mode and context:

IF MODE == tactical:
    SESSION_ID = "DIAG-" + STORY_ID
    # Example: "DIAG-STORY-127"
ELIF MODE == strategic:
    SESSION_ID = "RCA-" + rca_number
    # Example: "RCA-031"

devforgeai-validate phase-init ${SESSION_ID} --workflow=rca --project-root=.

Resume Detection: If resuming, read checkpoint:

Read(file_path="devforgeai/temp/.rca-checkpoint-${SESSION_ID}.yaml")

Extract current_phase and phase_completion to determine where to resume.

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=rca --from={prev} --to={phase_id}
       IF exit != 0: HALT

    2. LOAD: Read(file_path=".claude/skills/spec-driven-rca/phases/{phase_files[phase_id]}")

    3. 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

    4. RECORD: devforgeai-validate phase-record ${SESSION_ID} --workflow=rca --phase={phase_id}

    5. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=rca --phase={phase_id} --checkpoint-passed
       IF exit != 0: HALT

Phase Index

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

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}-rca-phase-state.json Session Memory: .claude/memory/sessions/${SESSION_ID}-rca-session.md Checkpoint: devforgeai/temp/.rca-checkpoint-${SESSION_ID}.yaml

Reference Files (Progressive Loading)

References are loaded on-demand by each phase. Do NOT pre-load all references.

Asset Templates (Strategic Mode)

Integration with DevForgeAI Framework

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

Related Skills

• spec-driven-dev (triggers tactical mode on test failures)
• spec-driven-qa (triggers tactical mode on validation failures)
• spec-driven-stories (consumes RCA recommendations via /create-stories-from-rca)

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

• All 4 phases executed in order (00 → 01 → 02 → 03)
• No fix attempts before Phase 02 completion
• diagnostic-analyst subagent invoked in Phase 02
• At least one hypothesis with confidence >= 0.5
• Prescription includes specific file paths and actions
• Prescription returned to invoking workflow

Strategic Mode

• All 8 phases executed in order (00 → 01 → 02 → 04 → 05 → 06 → 07 → 08)
• diagnostic-analyst subagent invoked in Phase 02
• 5 Whys complete with evidence
• Root cause validated (4 criteria)
• RCA document created at devforgeai/RCA/RCA-{NNN}-{slug}.md
• 3+ recommendations with exact implementation details
• Self-containedness check passed
• Completion report displayed

Change Log