Spec Driven QA

Spec-Driven QA Validation

Validate story implementations through strict 6-phase QA workflow while enforcing coverage thresholds, anti-pattern detection, and spec compliance.

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?"

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. Fresh-context subagent execution - Subagents run in isolated context without accumulated bias
2. Binary CLI gates - devforgeai-validate phase-check/phase-complete/phase-record (compiled Rust, cannot be forged by LLM)
3. Hook enforcement - Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification - .claude/hooks/phase-steps-registry.json tracks every mandatory step

Execute-Verify-Gate 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, Task result)
• 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)

Validation Modes

Light (~10K tokens, 2-3 min)

• Build/syntax checks
• Test execution (100% pass required)
• Critical anti-patterns only
• Deferral validation (if deferrals exist)

Deep (~35K tokens, 8-12 min)

• Complete coverage analysis (95%/85%/80% thresholds -- ADR-010, non-negotiable)
• Comprehensive anti-pattern detection
• Full spec compliance (AC, API, NFRs)
• Code quality metrics
• Security scanning (OWASP Top 10)
• Deferral validation (if deferrals exist)

Parameter Extraction

Extract story ID and mode from conversation context. See .claude/skills/spec-driven-qa/references/parameter-extraction.md for the extraction algorithm.

Extraction methods: YAML frontmatter, file reference, explicit statement, status inference. Default mode: deep (if unable to determine).

Command Integration

Phase State Initialization [MANDATORY FIRST]

devforgeai-validate phase-init ${STORY_ID} --workflow=qa --project-root=.

Phase Orchestration Loop

FOR phase_num in [01, 02, 03, 04, 05, 06]:
    phase_id = phase_num

    1. ENTRY GATE: devforgeai-validate phase-check ${STORY_ID} --workflow=qa --from={prev} --to={phase_id} --project-root=.
       IF exit != 0: HALT

    2. LOAD: Read(file_path=".claude/skills/spec-driven-qa/phases/{phase_files[phase_id]}")

    3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-GATE 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 ${STORY_ID} --workflow=qa --phase={phase_id} --project-root=.

    5. EXIT GATE: devforgeai-validate phase-complete ${STORY_ID} --workflow=qa --phase={phase_id} --checkpoint-passed --project-root=.
       IF exit != 0: HALT

Required Subagents Per Phase

Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion.

Definition of Done Protocol

Deferral validation CANNOT be skipped (RCA-007). Deferred DoD items require user approval, story/ADR references, and deferral-validator subagent validation.

Load protocol details when needed:

Read(file_path=".claude/skills/spec-driven-qa/references/dod-protocol.md")

State Persistence

Location: devforgeai/workflows/${STORY_ID}-qa-phase-state.json

Workflow Completion Validation

IF completed_count < 6: HALT "WORKFLOW INCOMPLETE - {completed_count}/6 phases"
IF completed_count == 6: "All 6 phases completed - QA workflow validation passed"

Success Criteria

Light: Build passes, tests pass, no CRITICAL, deferrals valid, <10K tokens Deep: Coverage thresholds met, no CRITICAL/HIGH, spec compliant, quality acceptable, deferrals valid, status="QA Approved", <35K tokens

Reference Files Index

Local references (loaded per-phase on demand, NOT consolidated):

Assets:

• .claude/skills/spec-driven-qa/assets/config/coverage-thresholds.md
• .claude/skills/spec-driven-qa/assets/language-smoke-tests.yaml
• .claude/skills/spec-driven-qa/assets/templates/qa-report-template.md
• .claude/skills/spec-driven-qa/assets/traceability-report-template.md

Automation Scripts:

• .claude/skills/spec-driven-qa/scripts/generate_coverage_report.py
• .claude/skills/spec-driven-qa/scripts/detect_duplicates.py
• .claude/skills/spec-driven-qa/scripts/analyze_complexity.py
• .claude/skills/spec-driven-qa/scripts/security_scan.py
• .claude/skills/spec-driven-qa/scripts/validate_spec_compliance.py
• .claude/skills/spec-driven-qa/scripts/generate_test_stubs.py