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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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"
