---
name: spec-driven-coverage
description: >
  Validate epic-to-story coverage with gap detection and batch story creation using
  structural anti-skip enforcement. Implements 6 phases of the DevForgeAI coverage
  workflow using the Execute-Verify-Gate pattern at every step. Designed to prevent
  token optimization bias through lean orchestration, fresh-context subagent delegation,
  and binary CLI gate enforcement. Detects coverage gaps between epics and stories,
  generates visual coverage reports, and orchestrates batch story creation with failure
  isolation. Use when validating epic coverage, detecting story gaps, or batch-creating
  stories for uncovered features. Always use this skill when the user runs
  /validate-epic-coverage or /create-missing-stories.
allowed-tools:
  - Read
  - Glob
  - Grep
  - AskUserQuestion
  - Task
  - Bash(devforgeai/traceability/gap-detector.sh:*)
  - Bash(devforgeai/epic-coverage/generate-report.sh:*)
  - Bash(devforgeai-validate:*)
  - Skill
model: opus
effort: Medium
---

# 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/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

**If ambiguous or conflicts detected: HALT and use AskUserQuestion**

---

## Execution Model

See **`.claude/rules/core/anti-skip-behavior.md`** for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase State Initialization immediately.

---

## 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). Behavioral residue: `.claude/rules/core/anti-skip-behavior.md`.

---

## Validation Modes

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

| Mode | Phases Executed | Purpose |
|------|----------------|---------|
| `validate` | 00 → 01 → 02 → 03 | Gap detection + coverage report + display formatting |
| `detect` | 00 → 01 | Gap detection only, return structured data |
| `create` | 00 → 01 → 04 → 05 | Batch story creation from gaps + completion summary |

---

## 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=".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

| Phase | File | Name | Required Subagents |
|-------|------|------|--------------------|
| 00 | `phases/phase-00-initialization.md` | Initialization | None |
| 01 | `phases/phase-01-gap-detection.md` | Gap Detection | None |
| 02 | `phases/phase-02-coverage-report.md` | Coverage Report | None |
| 03 | `phases/phase-03-display-formatting.md` | Display Formatting | epic-coverage-result-interpreter |
| 04 | `phases/phase-04-batch-creation.md` | Batch Story Creation | None (delegates to spec-driven-stories) |
| 05 | `phases/phase-05-completion-summary.md` | Completion Summary | epic-coverage-result-interpreter |

---

## 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

| ID | Rule | Enforcement Phase | Reference |
|----|------|-------------------|-----------|
| BR-001 | Epic ID: case-insensitive, normalized to EPIC-NNN | Phase 00 | `references/business-rules.md` |
| BR-002 | Coverage: only stories with status >= Dev Complete count | Phase 01 | `references/business-rules.md` |
| BR-003 | Shell-safe escaping for feature descriptions in commands | Phase 03 | `references/business-rules.md` |
| BR-004 | Batch failure isolation: item N failure does not affect item N+1 | Phase 04 | `references/business-rules.md` |

---

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

| Reference | Loaded By | Purpose |
|-----------|-----------|---------|
| `references/shared-protocols.md` | Phase 00 | EVG pattern documentation, self-check violations |
| `references/parameter-extraction.md` | Phase 00 | Context marker extraction rules |
| `references/business-rules.md` | Phase 00, 01, 03, 04 | BR-001 through BR-004 definitions |
| `references/gap-detector-integration.md` | Phase 01 | Shell script invocation documentation |
| `references/story-quality-gates.md` | Phase 04 | RCA-020 evidence verification requirements |

---

## Success Criteria

| Mode | Success Condition |
|------|-------------------|
| `validate` | Gap data collected, coverage report generated, display formatted via subagent |
| `detect` | Structured gap data returned (JSON-compatible object with total_features, covered_features, missing_features, coverage_percentage) |
| `create` | All gaps processed (success or isolated failure), completion summary displayed |

---

## Change Log

| Date | Story | Change |
|------|-------|--------|
| 2026-03-18 | — | Created — migrated from validating-epic-coverage with EVG anti-skip enforcement |
| 2026-02-20 | STORY-457 | Original skill created (validating-epic-coverage) |

---

**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)
