prd-validator

name

prd-validator

description

Validate that implementation work satisfies the requirements, acceptance criteria, and guardrails defined in the Strategic PRD. Use this skill whenever you need to check compliance after a task or batch is implemented, during code review, or as a pre-merge gate. Trigger when the user says things like "validate this against the PRD", "check if this meets the requirements", "run a compliance check", "is this ready to ship", "does this satisfy the acceptance criteria", or "pre-merge check". The validator is adversarial by design: it executes typechecks, builds, and tests rather than trusting self-reports, and treats a dishonest fallback as a hard failure. It never builds or modifies code — it only checks.

Skill: prd-validator

Purpose: Validate that implementation work satisfies the requirements, acceptance criteria, and guardrails defined in the Strategic PRD. This skill checks compliance — it does not build or modify code, and it does not propose fixes (that is the learner's job).

---

When to Use

• After a task or batch is implemented, before marking it complete.
• After an impl sub-agent reports done or partial in the build loop (LOOP-STATE.md phase = validate).
• During code review as an automated compliance check.
• As a pre-merge gate in CI/CD pipelines (when tooling supports it).

Do not validate work an impl agent reported as blocked — the validator only runs against work the implementer claims is complete.

Core Principles

1. Validation is a checklist operation, not a reasoning task. The Strategic PRD defines what must be true; this skill checks whether it is true. Each acceptance criterion gets a literal verdict: pass | fail | partial-by-design | not-applicable, with a one-line citation (file:line, test name, or build output).

2. A validator that cannot execute is not validating. The validator is read-only against source but runs typecheck, build, lint, and test commands. Checking code by reading it and trusting that tests pass is reviewing, not validating. If the implementer says a test passes, run it.

3. Adversarial stance. Assume the implementation's self-report may be wrong. Verify claims against actual file state, test output, and build status. Without an adversarial check, the impl agent self-reports success and nothing catches the gap.

4. Dishonest fallback is a hard fail, never a partial. A partial-by-design is acceptable when the implementer declared it explicitly with a documented contract (a seam that couldn't be crossed, degraded visibly). A silent skip, a stubbed return value, a try/catch that swallows errors, or code that builds but does not actually deliver the AC is a HARD-FAIL. These are process signals, not retry-and-fix material.

---

Validation Workflow

Step 1: Load Task Context

Load the task context generated by prd-taskmaster for the task or batch being validated. This includes:

• Referenced requirement IDs and their acceptance criteria.
• Applicable guardrails (do's and don'ts).
• Relevant learnings.

If a CONTEXT-PACK.md exists for the project (generated by prd-context-pack), read it for the current frozen contracts and active ADR rules. If no task context exists (e.g. validating ad-hoc work), fall back to loading the rules summary YAML for the relevant PRD. If that doesn't exist either, load Sections 5, 6, and 8 of the Strategic PRD directly.

Step 2: Gather Implementation Context

Identify what was built:

• Changed files — from the impl agent's structured report (files_written + files_modified) when one exists, otherwise from git diff, staged changes, or a provided file list.
• The scope of the change (which components, services, or modules were touched).
• Any partials_by_design the implementer declared, with their documented contracts.

Step 3: Build the Checklist

Make the acceptance criteria explicit before checking anything. If the criteria are implicit ("the build is green"), make them explicit first — the validator runs the literal checklist; vague criteria produce vague validation.

The checklist always includes the cross-cutting checks, regardless of what the ACs cover:

• Typecheck passes for the touched scope.
• Tests pass for the touched scope.
• No file outside the declared change set was modified (git diff --name-only against the branch point).
• No frozen contract (schema, ADR-pinned rule) was modified without a corresponding ADR amendment in scope.
• No new console.log, TODO, or FIXME introduced beyond what the implementer declared.
• Every declared partial-by-design is honestly inert (no fake success, no silent state mutation, contract documented).

The cross-cutting checks are non-negotiable. Add them to every validation, not just when they seem relevant.

In the build loop, write the checklist to <project_scope>/validation/<batch_id>-CHECKLIST.md so the validator sub-agent runs it as a literal contract.

Step 4: Run the Checks

Two execution modes:

Loop mode (orchestrated build). Brief a validator sub-agent via the prd-agent-brief skill with role = validator. The agent definition (.claude/agents/validator.md) grants read-only access to source plus Bash for build/typecheck/test execution; its only write target is the validation report. Spawn via the Agent tool with subagent_type: validator. Set the token budget to roughly half the impl budget — validation is cheaper than implementation.

Standalone mode (direct invocation). Launch parallel sub-agents per domain represented in the task's requirements, plus always a Guardrails sub-agent that checks Section 6 compliance across all changed files. Run the cross-cutting checks in the orchestrating context (they need Bash). Skip domains with no requirements in the task.

Sub-agent delegation guidance: checklist verification does not need the strongest available model — route domain-check sub-agents to the smallest model that reliably follows a checklist and reads code accurately, and keep the strongest model for orchestration, aggregation, and judgment calls. Constrain each sub-agent's output to ~25 lines; verbose analysis wastes the aggregation step.

Sub-Agent: Guardrails Check

You are checking code changes for compliance with project guardrails.

## Changed Files
{CHANGED_FILES_LIST}

## Guardrails to Check
{GUARDRAILS_FROM_TASK_CONTEXT}

## Instructions
1. Read each changed file.
2. For each DO guardrail: verify the code follows it. Flag if not.
3. For each DON'T guardrail: verify the code does not violate it. Flag if it does.
4. Only check guardrails relevant to the changed files. Skip guardrails about domains not touched by this change.

## Output Format (STRICT — keep under 20 lines)
CHECK: Guardrails
STATUS: PASS | FAIL | PASS_WITH_WARNINGS
VIOLATIONS: None | <one per line: guardrail text → file:line → issue>
WARNINGS: None | <one per line>

Sub-Agent: Domain Requirements Check

You are checking code changes for compliance with {DOMAIN} requirements.

## Changed Files
{CHANGED_FILES_FOR_DOMAIN}

## Requirements to Verify
{REQUIREMENTS_WITH_ACCEPTANCE_CRITERIA}

## Relevant Learnings
{LEARNING_ENTRIES_FOR_DOMAIN}

## Instructions
1. Read each changed file.
2. For each requirement (by ID): mark each acceptance criterion pass | fail | partial-by-design | not-applicable, with a one-line citation.
3. For each learning entry: check whether the learned rule is being followed.
4. If you find evidence of a dishonest fallback (stubbed success, swallowed errors, faked output), mark it HARD-FAIL with the reason.
5. Only check items relevant to the changed files. Don't flag requirements that aren't addressed by this task.

## Output Format (STRICT — keep under 25 lines)
CHECK: {DOMAIN}
STATUS: PASS | FAIL | PASS_WITH_WARNINGS
AC_RESULTS: <one per line: REQ-ID/AC → pass | fail | partial-by-design | not-applicable → citation>
HARD_FAILS: None | <one per line: REQ-ID → what was faked or skipped>
LEARNING_COMPLIANCE: PASS | <one per line: L-XXX → violation>
WARNINGS: None | <one per line>

Step 5: Aggregate Results

Produce a concise compliance report. In the build loop, write it to <project_scope>/validation/<batch_id>-REPORT.md; standalone, present it directly:

## Validation: APPROVED | BLOCKED

**Task/Batch:** T-001 — Implement user authentication API
**PRD:** PRD-001

| Check | Status | Issues |
|-------|--------|--------|
| Cross-cutting | PASS | — |
| Guardrails | PASS | — |
| Tech | PASS | — |
| Product | FAIL | PR-03: password reset flow missing |

**Per-AC results:**
- PR-03/AC-1: fail — POST /auth/reset not implemented (no route in api/auth/)
- TECH-01/AC-2: partial-by-design — email service not configured; contract documented in impl report

**HARD-FAILs (0):** None
**Contract violations (0):** None

**Violations (1):**
- PR-03 (must): Password reset endpoint not implemented. Acceptance criterion "POST /auth/reset sends email within 30s" not met. **Fix:** Add /auth/reset endpoint with email service integration.

**Requirements coverage:** 5/6 met (83%)

Decision Framework

Condition	Verdict
All checks PASS or PASS_WITH_WARNINGS, partials-by-design verified honest	APPROVED
Any must requirement unmet	BLOCKED — provide specific findings (the learner and orchestrator decide the fix)
Any should requirement unmet	APPROVED_WITH_WARNINGS — note the gap, suggest follow-up
Any may requirement unmet	APPROVED — note as optional improvement
Learning violation detected	BLOCKED — the team already learned this lesson; it must be fixed
Dishonest fallback detected	BLOCKED — HARD-FAIL — a process signal, not retry-and-fix material; surface to the human
Cross-cutting check failed (out-of-scope file touched, frozen contract modified)	BLOCKED — CONTRACT-VIOLATION — a fan-out safety issue; surface to the human immediately

Learning violations are treated as seriously as must violations. The entire point of the learning mechanism is to prevent repeated mistakes. If a learning entry says "don't do X" and the implementation does X, that's a hard block.

Step 6: Update Loop State (loop mode only)

If LOOP-STATE.md exists:

• All pass: phase → learn, increment Learner debt by 1 (via the prd-loop skill). Report: Validation passed for <batch_id>. <N> ACs pass, <M> partial-by-design (documented).
• One or more fail: phase stays at validate. Surface failures to the orchestrator with the defect list verbatim. The orchestrator decides whether to re-brief an impl agent or escalate as a decision.
• Same defect in two consecutive batches: log a workaround signature via prd-loop Step 3e.
• Close the validator's fan-out registry row.

---

Escalation

The validator escalates to a human without issuing a verdict when:

• A must requirement appears impossible to satisfy given the current architecture (may indicate a PRD issue, not just an implementation gap).
• Two requirements conflict in practice (e.g. a performance requirement conflicts with a security requirement).
• The implementation intentionally deviates from a must requirement and includes documentation explaining why.

In loop mode, route escalations to the LOOP-STATE.md decision queue rather than interrupting immediately — the prd-decision-batch skill packages them. Exception: HARD-FAIL and CONTRACT-VIOLATION surface immediately; they are safety signals, not scope questions.

---

What This Skill Does NOT Do

• Does not build or modify code. Read-only against source; the only file it writes is the validation report.
• Does not modify the PRD. If it discovers a gap in the PRD (e.g. a requirement that's untestable), it flags it for prd-learner.
• Does not propose fixes. It diagnoses and cites; prescribing is the learner's and orchestrator's job.
• Does not make architectural decisions. If the implementation takes a different approach than the PRD suggests but still meets all requirements and acceptance criteria, that's a PASS.

---

Beyond PRD Compliance

This skill checks whether implementation satisfies the requirements, acceptance criteria, and guardrails in the Strategic PRD, and runs the project's typecheck/build/test commands as part of its cross-cutting checks. It is not a substitute for a full QA process.

UI and visual testing

PRD compliance for design requirements (e.g. DES-01: Chart builder is usable by someone who has never written SQL) can be partially verified by checking that the relevant components exist and follow spec — but visual correctness, layout fidelity, and interaction quality require separate tools.

Recommended approach:

• For visual regression testing, use a tool like Playwright (screenshot diffs) or Chromatic (Storybook-based).
• For accessibility validation (WCAG compliance), use axe-core or Lighthouse as part of CI.
• Claude Code with browser access can run basic interaction walkthroughs when given a running URL.

When a design requirement has an acceptance criterion that cannot be verified programmatically (e.g. "3/5 non-technical participants can complete the flow in under 3 minutes"), this skill flags it as cannot verify automatically rather than marking it pass or fail. Human or usability testing is required for those criteria.

Relationship to the full test suite

The validator runs the typecheck and tests for the touched scope as cross-cutting checks. Full-suite execution, load testing, security scanning, and other specialized verification remain separate steps — add them as explicit steps in the workflow YAML before or after prd-validator when the PRD demands them.

If the test suite passes but the validator still flags violations, the tests don't cover all PRD acceptance criteria. That gap is itself a finding worth capturing via prd-learner.

---

Token Optimization

• Delegate the checklist, keep the judgment. Route per-domain checklist verification to smaller models; the orchestrating context handles parsing, routing, aggregation, and escalation decisions.
• Strict output limits. Sub-agents are constrained to 20-25 lines of output. This prevents verbose analysis that wastes tokens in the aggregation step.
• Load task context, not the full PRD. The task context (or the project's CONTEXT-PACK.md) is the minimal set of requirements and guardrails needed. The full PRD is only loaded if neither exists.
• Skip irrelevant domains. If the task only touches backend code, don't launch a Design sub-agent even if the PRD has design requirements.