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.
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.
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:
Fresh-context subagent execution — diagnostic-analyst subagent in Phase 02 runs in isolated read-only context, preventing accidental state mutation during investigation
Binary CLI gates — devforgeai-validate commands enforce phase state transitions; cannot be forged by LLM
— Shell scripts in run outside LLM control
Hook enforcement
.claude/hooks/
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.
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
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
None
05
Recommendation Generation
No
Yes
phases/phase-05-recommendation-generation.md
None
06
RCA Document Creation
No
Yes
phases/phase-06-document-creation.md
None
07
Validation & Self-Check
No
Yes
phases/phase-07-validation.md
None
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"
