---
description: Validate increment with rule-based checks and AI quality assessment. Use when saying "validate", "check quality", or "verify increment".
version: 1.0.0
argument-hint: "[increment-id]"
---

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

```typescript
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](https://verified-skill.com/docs/reference/skills#validate)
