Spec-Driven Coverage Validation

Validate epic-to-story coverage gaps and orchestrate batch story creation through a strict 6-phase workflow with structural anti-skip enforcement.

Context files are THE LAW: tech-stack.md, source-tree.md, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

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"
• Summarizing instead of loading a reference file

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. Per-phase reference loading — Each phase loads its reference files FRESH via Read() (not consolidated from memory)
2. Binary CLI gates — devforgeai-validate phase-check/phase-complete/phase-record (compiled binary, cannot be forged by LLM)
3. Checkpoint-based state tracking — Phase state JSON tracks current_phase, phases_completed, active_phases
4. Artifact verification — Phase state file verified via Glob(), outputs verified on disk via Grep()

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

• EXECUTE: The exact action to perform (Read, Glob, Grep, Bash, Task, Skill)
• VERIFY: How to confirm the action happened (file exists, content matches, exit code, data key populated)
• 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. (Reference: RCA-001, RCA-002, STORY-457)

Validation Modes

Three modes determine which phases execute. The mode is set by the invoking command via context markers.

Phase State Initialization

Before any phase executes, initialize phase state tracking.

EXECUTE:

Bash(command="devforgeai-validate phase-init ${IDENTIFIER} --workflow=coverage --project-root=. 2>&1")

Where ${IDENTIFIER} is ${EPIC_ID} (e.g., EPIC-015) or COVERAGE-ALL for all-epics mode.

VERIFY: Exit code 0 or 2 (exit code 2 = identifier format not recognized, proceed with backward compatibility).

If exit code 127: CLI not installed. Continue without CLI gates but execute ALL phases and steps regardless.

Phase Orchestration

Determine active phases from the mode, then execute each in sequence:

active_phases = MODE_ROUTES[mode]
  validate: ["00", "01", "02", "03"]
  detect:   ["00", "01"]
  create:   ["00", "01", "04", "05"]

FOR phase_num in active_phases:
  1. ENTRY GATE: Verify previous phase completed (check phase state or first phase)
  2. LOAD: Read(file_path="src/claude/skills/spec-driven-coverage/phases/phase-{phase_num}-{name}.md")
     - If Read fails, try: Read(file_path=".claude/skills/spec-driven-coverage/phases/phase-{phase_num}-{name}.md")
  3. EXECUTE: Follow ALL EVG triplets in the phase file — no skipping
  4. RECORD: devforgeai-validate phase-record ${IDENTIFIER} --phase={phase_num} --project-root=. 2>&1
  5. EXIT GATE: Verify phase artifacts exist before proceeding

CRITICAL: Execute EVERY step in EVERY active phase. The mode router only controls WHICH phases run — within each phase, ALL steps are mandatory.

Phase Index

Command Integration

This skill is invoked by two commands with context markers:

/validate-epic-coverage context markers:

**Epic ID:** ${EPIC_ID} (or "all")
**Mode:** validate
**Prompt Mode:** interactive | quiet | ci

/create-missing-stories context markers:

**Epic ID:** ${EPIC_ID}
**Mode:** detect (first invocation) OR create (second invocation)
**Sprint:** ${SPRINT}
**Priority:** ${PRIORITY}
**Points:** ${POINTS}
**Individual Priority:** true | false
**Individual Points:** true | false
**Batch Mode:** true
**Batch Total:** ${gap_count}
**Created From:** /create-missing-stories

Business Rules

Performance Targets

• Single epic validation: < 500ms
• All epics (20 epics, 200 stories): < 3 seconds
• Batch story creation: ~3 seconds per story
• Batch of 10 stories: < 30 seconds total

Reference Files Index

Each phase loads only its required references. No consolidated loading.

Success Criteria

Change Log

Created: 2026-03-18 Migrated from: validating-epic-coverage (STORY-457) Pattern: Spec-driven skill with Execute-Verify-Gate anti-skip enforcement Predecessor ADR: ADR-020 (Structural Changes Authorization)