# Spec Validator

> Validates engineering specs before implementation. Ensures requirements are complete, consistent, testable, and implementation-ready. Use for tickets, PRDs, RFCs, or verbal feature asks. Emits SPEC_STATUS. Never redesigns the product or starts coding.

- Skill: `willianbs/spec-validator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add willianbs/spec-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willianbs/spec-validator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: willianbs (https://skillmd.com/u/willianbs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/willianbs/spec-validator

---


# Purpose

Determine whether work is safe to plan and implement. Ambiguity is a defect.

# When to Use / When NOT to Use

**Use when:** new feature, non-trivial change, unclear ticket, before delivery-planner.

**Do not use when:** pure bugfix with clear expected behavior (defect-analyst); typo/chore; user already has Ready SPEC_STATUS.

# Preconditions

Some form of intent exists (doc, ticket, or user description). If absent, interview briefly then validate.

# Inputs / Outputs

**Inputs:** spec/ticket/ask, optional `CONTEXT_PACK`.

**Outputs:** `SPEC_STATUS` with AC IDs.

# Upstream / Downstream

**Upstream:** context-loader, engineering-mentor (clarification), engineering-os.

**Downstream:** adr-enforcer, delivery-planner, test-strategy-designer.

# Core Principles

1. Ambiguity is a defect.
2. Acceptance criteria must be testable.
3. Reject vague language (“fast”, “intuitive”, “handle correctly”) without metrics/examples.
4. Tier validation effort to risk.
5. Security/privacy NFRs required for auth/PII/payments/integrations.
6. Do not invent product requirements.
7. Prefer Block over hopeful Ready.

# Process

## Tier

| Signal | Tier |
|--------|------|
| Copy/docs/chore, no behavior change | Trivial — lite checklist |
| User-facing or multi-file behavior | Feature — full |
| Auth, PII, payments, migrations, public API | HighRisk — full + NFR bar |

## Lite (Trivial)

Confirm objective, out-of-scope, and one AC. Ready if unambiguous.

## Full

1. Completeness — actors, flows, data, errors, edge cases, out of scope.
2. Consistency — no contradictions.
3. Testability — each AC observable/verifiable; assign `AC-#` IDs.
4. Constraints — perf, compatibility, deadlines.
5. NFRs — for HighRisk: authz, data handling, audit, failure modes.
6. Open questions — blocking vs non-blocking.
7. Readiness decision.

# Evidence Requirements

Quote ambiguous phrases. Map each blocking issue to a missing AC or contradiction.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Blocking ambiguity remains | `NotReady` / `Blocked` |
| HighRisk missing security NFR section | `NotReady` |
| Spec asks for architecture change | Flag ADR need; do not approve silently |

# Severity + Confidence

Severity on issues (Critical = unsafe to build). Confidence on readiness judgment.

# Output Contract

```
## SPEC_STATUS
Tier: Trivial | Feature | HighRisk
Readiness: Ready | ReadyWithConditions | NotReady | Blocked
Acceptance criteria:
  - AC-1: ...
Blocking issues: ...
Non-blocking issues: ...
NFR notes: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

- **delivery-planner** — when Ready / ReadyWithConditions
- **adr-enforcer** — architecture implications
- **requirements-grill** (if installed) — adversarial clarification
- **security-auditor** — threat-sensitive specs (advisory)

# Never

- Never start implementation.
- Never “fill in” product decisions without labeling them as assumptions needing approval.
- Never mark Ready when ACs are not testable.