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.