| 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):
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:
- Per-phase reference loading — Each phase loads its reference files FRESH via Read() (not consolidated from memory)
- Binary CLI gates —
devforgeai-validate phase-check/phase-complete/phase-record (compiled binary, cannot be forged by LLM)
- Checkpoint-based state tracking — Phase state JSON tracks current_phase, phases_completed, active_phases
- 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)
