anton-abyzov/plugins/specweave/skills/validate

Validate Increment

Project Overrides

Skill Memories: If .specweave/skill-memories/validate.md exists, read and apply its learnings.

Project Context

Project Context: If .specweave/config.json exists, read it for testing mode, TDD enforcement, and multi-project settings. Check for active increments in .specweave/increments/*/metadata.json.

You are helping the user validate a SpecWeave increment with optional AI-powered quality assessment.

Usage

sw:validate <increment-id> [--quality] [--export] [--fix] [--always]

Flags: --quality (AI assessment) | --export (suggestions to tasks.md) | --fix (auto-fix HIGH issues) | --always (save quality preference)

Two-Gate Validation System

• Gate 1 (Rule-Based): Always runs, free, 130+ automated checks
• Gate 2 (LLM-as-Judge): Optional (--quality), AI-powered, ~2K tokens

Gate 1 catches structural issues first; Gate 2 catches semantic issues.

Workflow

Step 1: Parse Arguments

1. Extract increment ID: normalize to 4-digit format ("1" -> "0001", "0153-feature-name" -> "0153")
2. Extract flags: --quality, --export, --fix, --always
3. Validate increment exists in .specweave/increments/. Show error with available increments if not found.

Step 1.5: Sync AC Status

Before validation, sync spec.md ACs with tasks.md completion status to prevent false positives:

const acManager = new ACStatusManager(projectRoot);
const acSyncResult = await acManager.syncACStatus(incrementId);

This is idempotent and prevents "0 ACs checked" false positives from async hooks.

Step 2: Run Rule-Based Validation

Run 130+ checks across 7 categories. Run structure validation FIRST.

| Category | Checks | Purpose | |----------|--------|---------| | Structure | 5 | Single tasks.md, allowed root files, metadata.json valid | | Three-File Canonical (ADR-0047) | 10 | tasks.md has Implementation (not ACs), spec.md has no task IDs, plan.md has no AC sections | | Consistency | 47 | Cross-document alignment (stories -> plan -> tasks -> tests) | | Completeness | 23 | Required sections in spec.md, plan.md, tasks.md | | Quality | 31 | Tech-agnostic spec, testable ACs, actionable tasks (<1 day) | | Traceability | 19 | TC format, ADR refs, diagram refs | | AC Coverage | 6 | All ACs have tasks, no orphan tasks, valid US linkage |

Key three-file rules (ADR-0047):

• tasks.md: MUST have **Implementation**: and **AC-IDs**: references. Must NOT have **Acceptance Criteria**: or user story language.
• spec.md: MUST have ## Acceptance Criteria. Must NOT have task IDs (T-001).
• plan.md: Must NOT have AC sections or task checkboxes.

Display category pass/fail counts and AC coverage percentage.

Step 3: Determine Quality Assessment

1. If --quality flag: run quality assessment (skip prompt)
2. Else: prompt user with Y/N/A (Always) choice

Step 4: Run AI Quality Assessment (If Approved)

Use CLI: specweave qa <id> --pre (or increment-quality-judge-v2 skill auto-activates).

6 quality dimensions:

| Dimension | Weight | |-----------|--------| | Clarity | 0.20 | | Testability | 0.25 | | Completeness | 0.20 | | Feasibility | 0.15 | | Maintainability | 0.10 | | Edge Cases | 0.10 |

Display: overall score (0-100), per-dimension scores, issues (MAJOR/MINOR), and actionable suggestions.

Step 5: Handle Export Flag

If --export: parse suggestions, add to tasks.md as prioritized tasks with [HIGH]/[MEDIUM] labels and estimates.

Step 6: Handle Fix Flag

If --fix: identify HIGH-priority fixable issues, generate diffs, show to user for confirmation, apply if approved, then re-validate.

Only fix issues with clear unambiguous improvements. Skip domain-specific or ambiguous issues.

Step 7: Handle Always Flag

If --always: enable validation.quality_judge.always_run: true so future validations auto-run quality assessment.

Step 8: Generate Validation Report

Save detailed report to: .specweave/increments/<id>/reports/validation-report.md

Report includes: executive summary, rule-based results by category, AI quality scores, issues, suggestions, recommendations, and validation history.

Scoring & Grading

| Score | Grade | |-------|-------| | 90-100 | EXCELLENT | | 80-89 | GOOD | | 70-79 | ACCEPTABLE | | <70 | NEEDS WORK |

Pass/fail gate: Rule-based must pass all CRITICAL checks. Quality score is advisory (no hard gate).

Related

• increment-quality-judge skill: AI assessment engine
• sw:done: validates before closing
• specweave qa <id>: CLI equivalent

Resources

• Official Documentation