Spec Driven Coverage

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

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