/validation-pipeline

name: "validation-pipeline"
description: "Runs multi-stage validation gates with per-step scoring, pass/fail verdicts, and aggregate quality reports. Use when validating requirements, code, or artifacts through structured gate enforcement before merge or release."
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/validation-pipeline.yaml

Validation Pipeline

Purpose

Run structured validation pipelines that execute steps sequentially, enforce gates at blocking failures, and produce scored reports. Uses `.claude/helpers/validation-pipeline.cjs` with 13 requirements validation steps (BMAD-003).

Activation

• When validating requirements documents
• When running structured quality gates
• When assessing document completeness, testability, or traceability
• When invoked via `/validation-pipeline`

Quick Start

# Validate a requirements document (all 13 steps)
/validation-pipeline requirements docs/requirements.md

# Validate with specific steps only
/validation-pipeline requirements docs/requirements.md --steps format-check,completeness-check,invest-criteria

# Continue past blocking failures
/validation-pipeline requirements docs/requirements.md --continue-on-failure

# Output as JSON
/validation-pipeline requirements docs/requirements.md --json

Workflow

Step 1: Read the Target Document

Read the file specified by the user. If no file is provided, ask for one.

Read the target document using the Read tool.
Store the content for pipeline execution.

Step 2: Select Pipeline

Choose the appropriate pipeline based on the user's request:

| Pipeline | Steps | Use Case | |----------|-------|----------| | `requirements` | 13 | Requirements documents, PRDs, user stories |

Additional pipelines can be added to `.claude/helpers/validation-pipeline.cjs`.

Step 3: Execute Pipeline

The pipeline helper (`.claude/helpers/validation-pipeline.cjs`) handles execution:

1. **Sequential execution** — steps run in order, each receiving results from prior steps 2. **Gate enforcement** — blocking steps that fail halt the pipeline (unless `--continue-on-failure`) 3. **Per-step scoring** — each step produces a 0-100 score with findings and evidence 4. **Weighted rollup** — overall score uses category weights (format=10%, content=30%, quality=25%, traceability=20%, compliance=15%)

Requirements Pipeline Steps (13 total)

| # | Step ID | Category | Severity | What It Checks | |---|---------|----------|----------|----------------| | 1 | `format-check` | format | blocking | Headings, required sections, document length | | 2 | `completeness-check` | content | blocking | Required fields populated, acceptance criteria present | | 3 | `invest-criteria` | quality | warning | Independent, Negotiable, Valuable, Estimable, Small, Testable | | 4 | `smart-acceptance` | quality | warning | Specific, Measurable, Achievable, Relevant, Time-bound | | 5 | `testability-score` | quality | warning | Can each requirement be tested? | | 6 | `vague-term-detection` | content | info | Flags "should", "might", "various", "etc." | | 7 | `information-density` | content | info | Every sentence carries weight, no filler | | 8 | `traceability-check` | traceability | warning | Requirements-to-tests mapping exists | | 9 | `implementation-leakage` | quality | warning | Requirements don't prescribe implementation | | 10 | `domain-compliance` | compliance | info | Alignment with domain model | | 11 | `dependency-analysis` | traceability | info | Cross-requirement dependencies identified | | 12 | `bdd-scenario-generation` | quality | warning | Can generate Given/When/Then for each requirement | | 13 | `holistic-quality` | compliance | blocking | Overall coherence, no contradictions |

Step 4: Report Results

Format the pipeline result as a structured report:

# Validation Report: Requirements Pipeline

**Overall**: PASS/FAIL/WARN | **Score**: 85/100 | **Duration**: 42ms

## Step Results
| # | Step | Status | Score | Findings | Duration |
|---|------|--------|-------|----------|----------|
| 1 | Format Check | PASS | 100 | 0 | 2ms |
| 2 | Completeness | WARN | 60 | 2 | 5ms |
...

## Blockers
- (blocking findings listed here)

## All Findings
- [HIGH] Missing acceptance criteria: Requirement US-104 has no AC
- [MEDIUM] Vague term: "should" used 5 times without specifics
...

Step 5: Record Learning

After pipeline execution, record the outcome for learning:

// Store validation pattern
memory store --namespace validation-pipeline --key "req-validation-{timestamp}" --value "{score, findings_count, halted}"

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `pipeline` | string | `requirements` | Pipeline type to run | | `file` | string | required | Path to document to validate | | `--steps` | string | all | Comma-separated step IDs to run (e.g., `format-check,completeness-check`) | | `--continue-on-failure` | boolean | false | Skip blocking gates | | `--json` | boolean | false | Output as JSON instead of markdown | | `--metadata` | object | {} | Additional context for steps |

Integration Points

• **qe-requirements-validator agent** — delegates structured validation to this pipeline
• **qe-quality-gate agent** — uses pipeline for gate evaluation
• **YAML Pipelines** — can invoke validation steps as workflow actions
• **MCP** — accessible via `pipeline_validate` tool

Output Schema

The pipeline produces a `PipelineResult` object (see `schemas/output.json`):

{
  pipelineId: string;
  pipelineName: string;
  overall: 'pass' | 'fail' | 'warn';
  score: number;           // 0-100 weighted average
  steps: StepResult[];     // per-step details
  blockers: Fi