# Build Validate > Review a build's PREMISES — the three-to-five things that must be true about the world for the design to be right — once, after build-probe and before build-plan. Not a plan review. Not a per-round gate. Spawns 2-3 reviewers against the premise page and the probe run's UNPROVABLE list, and asks one question: is the frame right. Use when a build's frame is new or contested — a new module whose oracle is not obvious, a schema change that alters what a field MEANS, or a reversal like "we check their sheet" becoming "we produce it". Triggers — "validate the premises", "is the frame right", "check my assumptions before I plan", "/build validate". Do NOT use on a plan, on a repair round, or on a running system. - Skill: `shawnclybor/build-validate` (Agent Skill) - Install (CLI): `npx skillmds@latest add shawnclybor/build-validate` - Raw SKILL.md: https://api.skillmd.com/api/skills/shawnclybor/build-validate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: shawnclybor (https://skillmd.com/u/shawnclybor) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/shawnclybor/build-validate --- # Build Validate — the premise check **One question: is the frame right?** Not "is the plan complete", not "is this number correct", not "could a careless implementer game this criterion". Those have cheaper detectors and this stage must not spend itself on them. ## Why this is scoped so narrowly — the measurement Twenty-one recorded rounds across seven slugs under the old design, which reviewed *plans*: ``` round-1 must-fix: 8, 13, 14, 15, 12, 12, 9 mean 11.9, every time total must-fix: 175 self-inflicted: 78 = 45% (a finding in text the PREVIOUS round's repair wrote) ``` Three things follow, and the design is built on them. **A freshly-written plan carries ~12 must-fix regardless of care.** Seven independent first rounds, range 8–15. That is not a quality signal; it is what happens when prose asserts things about code nobody has run. **Later rounds mostly grade their own damage.** Repair rewrites the document, the panel re-reads fresh surface, forever. One slug reached *zero* must-fix at round 6, took on new scope, and was back to 12 at round 7 — with `review-drift.py` scoring 12 of 12 self-inflicted. **Sorting one real round by cheapest detector, only 3 of 15 findings needed judgment.** Seven were checkable facts (a probe settles those in seconds). Five were plan incoherence (`check-plan-soundness.py` settles those in under a second). Three were frame errors — and those three were worth the whole exercise, because nothing else finds them. So: probe the facts, gate the structure mechanically, and spend this stage only on the frame. Premises do not change when you fix a typo, which is precisely why reviewing them cannot spiral. ## When to use Run once, when a build's frame is **new or contested**: - a new module whose oracle is not obvious — *what makes this output right?* - a schema change that alters what an existing field **means** - a reversal of direction — "we audit their sheet" becoming "we generate it" - any `UNPROVABLE` entry that `build-probe` carried forward If you can state every premise in one line and none is in dispute, **skip this stage and say so in `state.json`.** Skipping a premise check on settled ground is correct, not a shortcut. ## When NOT to use — each of these has a cheaper detector | Not this | Use instead | |---|---| | A plan's task list | `check-plan-soundness.py` — 8 mechanical classes, under a second | | A number, count, filename or line reference | `build-probe` | | A repair round after findings were fixed | Nothing. Re-run the probes and the mechanical gate | | A running system with a mutation-backed suite | The suite. Run the thing | | A per-iteration code change | `build-execute`'s conditional review — and it is conditional | ## Phase 1: WRITE THE PREMISE PAGE One page. `.claude/PRPs/{slug}/premises.md`. Three to five entries, each in this shape: ```markdown ### P1. {The premise, as a claim about the world — one sentence} **If this is wrong:** {what in the build becomes incoherent} **Evidence:** {a probe id, a document, a person who said it — or "none, this is an assumption"} **Who can settle it:** {a probe / the user / a named person at the client} ``` A premise is load-bearing: if it is false, some part of the design stops making sense. *"The account numbers we bind on are printed on the bills"* is a premise. *"Task 4 should come before Task 5"* is not — that is the plan's business. Carry every `UNPROVABLE` from `probe.md` in as a premise. That list is this stage's agenda. **If a premise can be settled by asking the user, ask the user.** One question, five seconds, and you are done. Measured: on one build, three frame errors all reduced to a single question the owner could have answered instantly — five agents spent 45 minutes discovering the question existed. Discovering the question is this stage's value; answering it usually is not. ## Phase 2: DECLARE THE PASS CONDITION Write it into `validate.md` **before** spawning anything. A bar set after seeing the findings is not a bar. ```markdown ### Pass condition (declared {ISO}, before agents ran) - Scope: the premises in premises.md. Nothing else is in scope, including the plan. - PASS if: every premise is settled — confirmed by evidence, or decided by the owner. - FAIL if: any premise is contradicted by the evidence, or any load-bearing premise is unstated and only surfaced by review. ``` ## Phase 3: REVIEW (2-3 agents, one message) Spawn in a single message. Every reviewer gets the pass condition from Phase 2, the scope line, and `premises.md` with the probe run's `UNPROVABLE` entries already carried in. Each reviewer is a **named agent**, not `general-purpose`. Each of the three questions below is one agent's standing lens, and this stage runs exactly once — there is no later round to correct a reviewer that improvised its own frame. ### Agent 1 — Premise auditor (`adversarial-reviewer`, Opus) Finds the unstated frame, which is the failure mode that matters. ``` Agent( subagent_type="adversarial-reviewer", description="Surface unstated premises in {slug}", prompt="Scope: premises only. The plan, its task list and its ordering are OUT of scope. Design: . Stated premises: . Which premises is this design relying on that are NOT stated? For each, write it as a one-sentence claim about the world and say what in the build becomes incoherent if it is false. Do not report numbers, counts, filenames or line references — build-probe owns those. Findings only, no edits." ) ``` ### Agent 2 — Falsifier (`evidence-auditor`) Its output contract is already CONTRADICTED / SUPPORTED / NO EVIDENCE against a source. ``` Agent( subagent_type="evidence-auditor", description="Falsify each stated premise against the sources", prompt="Scope: the stated premises only. Premises with their Evidence lines: . Sources to read: . For EACH premise report exactly one of CONTRADICTED / SUPPORTED / NO EVIDENCE, naming the file and line that decides it. NO EVIDENCE is a valid and useful verdict — do not upgrade it to SUPPORTED because the premise sounds reasonable. Findings only, no edits." ) ``` ### Agent 3 — Oracle auditor (`chaos-engineer`) Only when the build produces a value a human will act on. This is the frame problem's home: a criterion satisfiable by a module that behaves honestly while the deliverable stays useless. ``` Agent( subagent_type="chaos-engineer", description="Audit the correctness oracle for {slug}", prompt="Scope: the correctness oracle, not the code and not the plan. Design: . Premises: . What makes this output right, and how would we know if it were subtly wrong? Is the correctness check a property of the module, or of the thing a person reads? Name one concrete case where every stated criterion passes and the output is still wrong for its reader. Findings only, no edits." ) ``` No pattern auditor, no completeness auditor, no anti-pattern auditor — mechanical checks own those now. No fact-checker; `build-probe` owns facts. Adding a fourth lens re-opens the spiral this stage was scoped to avoid. ## Phase 4: RECORD AND REPORT ```bash python3 .claude/hooks/review-drift.py record --must N --should N --note N \ --self-inflicted 0 --round-note "premise review" ``` Write `validate.md`: the pass condition, each premise with its verdict, and the decisions the owner made. **A premise the owner settled is settled** — record it and never re-open it. ## The stop rule **One round.** There is no round 2 on premises: a premise is confirmed, contradicted, or decided, and none of those states improves by reviewing again. If new premises appear later, that is a new frame and a new single round, not a second pass at this one. If you find yourself wanting another round, the thing you actually want is either a probe (write it) or a decision from the owner (ask for it). ## Output ``` ## Premises: {slug} **Reviewed:** N premises ({N} carried from probe.md as UNPROVABLE) **Settled:** {N} by evidence · {N} by the owner **Unstated premises surfaced:** {N} **Verdict:** PASS / FAIL ### Next step PASS → `build-plan {slug}` — capped at ONE runnable increment. FAIL → the frame is wrong. Fix the PRD, re-probe, and run this once more. ``` ## Guidelines - This skill is READ-ONLY on the build. It writes `premises.md` and `validate.md` and nothing else. - If a premise review produces a finding about a task, you are in the wrong stage. Drop it. - A build with no contested premises should skip this entirely. Record the skip; do not manufacture premises to justify a run. - PASS means the frame is sound. It does not mean the build will work — that is the acceptance driver's job, and the driver is written red before any of this is worth anything.