Validate Spec

---
name: validate-spec
description: "Adversarially validate a draft spec BEFORE the maintainer sees it. Use after write-spec finishes, or when the user asks to validate/review a spec. A draft without a validation record cannot be approved or built."
trigger: /validate-spec
---

# /validate-spec — attack the spec before it costs anything

Code has gates L0–L8; this is the spec-side gate (S1–S4). Two motivating incidents:
- **Correctness (2026-07-02):** a spec promised "on Haiku this'd be ≈ $7.40" —
  unmeasurable, since a cheaper model might not have managed the task. Machines and
  one reviewer missed it; the maintainer caught it. → S1/S2.
- **Worth (2026-07-05):** a spec (`--pr <N>` backfill) was fully buildable and
  survived S2 — and was still an edge case not worth building. The pipeline hardened
  its *correctness* while its *worth* was self-graded ("this repo's own cleanup"),
  and the maintainer caught it at button 1. → S3.

A spec can be correct, measurable, and feasible and still not be worth building. This
gate now attacks BOTH: is it right, AND is it worth it.

## S1 — Invariant audit (self)

For every Requirement and every user-facing line the spec promises, ask:
- **Measurable?** Can this be computed deterministically from the transcript (or other
  local inputs) alone? If it needs a prediction, a judgment, or data we don't have,
  it is banned or must be reframed as labeled arithmetic / an empirical measurement.
- **I1–I6 clean?** Especially I2 (no fabricated dollars) and I6 (facts, not rankings).
- **Honest under adversarial reading?** Would a skeptical HN commenter call this line
  a lie? Rewrite until the answer is no.

## S2 — Independent critic (different model family)

Run a Codex (or non-Claude) review of the spec file with this exact framing: "Attack
this spec: (1) claims that cannot be measured or verified; (2) requirements with no
test-matrix row; (3) feasibility against the cited `file:line` seams; (4) scope beyond
the stated goal; (5) the weakest requirement — argue it should be cut; (6) **worth —
argue this should NOT be built at all: is it an edge case, over-engineering, or a
recovery for a rare workflow miss? Who concretely hits this, and how often? Is the
do-nothing outcome actually bad? Is there a smaller non-feature fix (a doc, a
one-liner, nothing)?**" Builder and critic must be different contexts; never validate
your own draft in-context. S2 does NOT bless worth — it supplies an independent worth
attack; the verdict is S3's, and the decision is the maintainer's (button 1).

## S3 — Worth-building gate (adversarial, not self-graded)

Correctness is necessary, not sufficient. Before the spec reaches the maintainer, answer
these in the Validation record — concretely, not "the repo needs it":
- **Who + how often.** Name the actual user and the real frequency of the scenario. "A
  contributor who X, ~N times per release" — not "this could be useful."
- **One-off vs recurring.** Is the motivating case a single cleanup/incident, or a need
  that recurs? A one-off motivation is a park signal, not a build signal.
- **Do-nothing.** State exactly what happens if this is never built. If that outcome is
  honest/acceptable (e.g. "the PRs stay receipt-less, which is fine"), the bar to build
  is high.
- **Smaller fix.** Is there a non-feature answer — a doc line, a tiny script, or nothing?
  If a doc closes 80% of the value, ship the doc.
- **Steelman the cut.** Write the strongest case for NOT building it. If that case is
  stronger than the build case, park the spec (Tombstone) rather than ship it to approval.
- **Kill criterion dry-run** (from the write-spec interview): what evidence already
  suggests it survives? "None yet" → name the cheapest experiment, or park.

Record a one-line **verdict: build now / defer / cut**. `defer`/`cut` → the spec is
parked with a Tombstone and does NOT go to the maintainer as a build candidate. Do not
let S2 surviving (correctness) be mistaken for S3 passing (worth) — the `--pr` backfill
spec passed S2 and failed S3.

## S4 — Mechanical lint

`node scripts/spec-lint.mjs specs/SPEC-NNNN-*.md` — frontmatter enum valid, every `Rn`
appears in the Test matrix, required sections present, no inline type definitions.

## Record & handoff

Append a `## Validation` section to the spec: date, S1 outcome, S2 findings (accepted /
rejected, one line each — including the worth attack), S3 worth answers + the one-line
**verdict (build now / defer / cut)**, S4 pass. Fixes go into the draft first.

Only a spec whose S3 verdict is **build now** goes to the maintainer as a build
candidate; approval (button 1) then means approving a spec that survived BOTH the
correctness attack and the worth attack, with the record attached. A `defer`/`cut`
verdict parks the spec with a Tombstone instead. This skill never sets `approved`.