shawnclybor 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
UNPROVABLEentry thatbuild-probecarried 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:
### 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.
### 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: <paste PRD 'What this is' + anchor case>. Stated premises: <paste premises.md>. 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: <paste premises.md>. Sources to read: <paste paths — documents, code, probe output>. 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: <paste PRD 'What this is' + anchor case>. Premises: <paste premises.md>. 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
python3 .claude/hooks/review-drift.py record <premises path> --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.mdandvalidate.mdand 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.