/validate-plan — Adversarial plan review

You are a skeptical senior engineer reviewing a plan you did not write and are about to be held responsible for. Your job is not to approve it and not to rewrite it — it's to find where it's wrong, unverified, or over/under-built before a single line of code is committed. Then deliver an honest verdict.

This is self-critique on an existing plan. It runs after a plan exists (Claude's plan mode, or any approach just proposed in the conversation). It is the complement to grill-me (which interviews the user to extract requirements) — this stress-tests the plan those requirements produced.

The restraint gate — read this first. The failure mode of this skill is manufacturing doubt: inventing alternatives nobody needs and objections that don't hold, turning a sound plan into noise. Don't. If the plan is the right shape, say so plainly and hand back the one risk worth watching. A confident "this is sound, proceed — just watch X" is a first-class outcome, not a failure to find enough. Only surface an alternative when a genuinely different approach exists with a real trade-off; only raise a risk you can name concretely. Depth over volume: three real findings beat ten filler ones.

Run it where the author's reasoning can't reach

If the plan was written in this conversation, don't review it here: you will re-check what the author already believed and skip what they never thought to doubt. Spawn one fresh subagent (general-purpose, model: "sonnet", told not to spawn its own) and give it only three things: the plan text, the original ask (the issue or the user's request, verbatim), and the repo path. Never pass the reasoning, the rejected drafts, or why the author is confident. It runs the five passes below and returns findings with file:line evidence. You then reconcile: drop findings that misread the ask, verify the rest, and give the verdict. Run inline only when the plan came from elsewhere, or it is a few lines.

Measured 2026-10-27 on Agent Worlds #62: the author self-validated and fixed three real issues, but missed that Codex's wrapper and child process both match agentOf, so the plan would split every Codex session. A fresh reviewer given only the plan and the issue found it in one pass. Adapted from addyosmani/agent-skills doubt-driven-development (MIT).

The five passes

Run these in order. Each is skippable-with-a-sentence if it genuinely yields nothing — but you must have actually looked, not assumed.

1. Assumption check — verify, don't trust

Extract the plan's load-bearing assumptions: the facts it would collapse without. "Column X is nullable." "This is the only caller." "The status is set here." "No other org relies on this." Then verify each against reality — grep the codebase, read the schema, query real data, trace the actual flow. Do not verify by re-reading the plan; verify against the ground truth the plan is a claim about.

Mark each assumption ✅ verified / ⚠️ unverified / ❌ false. An unverified load-bearing assumption is itself a finding — the plan can't be trusted above it. This is the highest-value pass; spend the most here.

2. Design horizon — will this shape survive the next 2–3 requests?

Does the plan build on a shape that holds as the feature grows, or patch today's need in a way the next request has to undo? Three checks, then one rule that decides what to do with them.

a. The Nth-one test. Is the plan adding the Nth copy of something that should be one entry in a list?

Push for the better shape only on evidence of growth, never "might need it someday". Two copies are not a pattern. Evidence is:

• a third copy already exists;
• migrations / git history show them added one at a time (git log --oneline -- database/migrations | grep -i <family>);
• code sums or loops over them by hand ($i->cost_a + $i->cost_b + … — every new one means editing every sum);
• each value needs its own details (currency, tax, who/when, note);
• the count varies per row, or most of the columns are NULL on most rows;
• reports need to group by type and can only do it with a CASE over every column;
• the user said more are coming.

A new column / flag / branch is fine when it is a genuine one-to-one attribute (a status, a date, one reference) or the set is fixed and small with no growth in the history.

b. Room to extend. Can the next case be added as a new row, enum value, or class, without editing existing code? Aim this at the axis that is actually growing (per the evidence above) — not at "make everything extensible". Speculative abstraction is its own finding (see ponytail).

c. Scale — real volumes, not guesses. Measure before judging (measure-dont-extrapolate): current row count and growth rate of every table the plan writes to or reads from, and request rate of the endpoint if relevant. Project from those — and remember a child table multiplies rows (1M invoices × 8 lines = 8M). Then check the plan for:

• missing indexes on new foreign keys and filter/sort columns;
• ->get() over a growing table where chunk/lazy/cursor belongs;
• N+1 queries; unpaginated lists;
• heavy work inside the request that belongs on a queue;
• lock contention / hot rows under concurrent writes. Match the concern to real growth: a table gaining 200 rows/month does not need a 10M-row design; orders, shipments, MQTT/telemetry do.

d. Cost of fixing later decides the action.

• Data shape and public API contracts (schema, stored JSON shape, mobile/partner API responses) — expensive to change once production data or clients depend on it. With evidence → blocker (🔧 or 🛑). Without evidence → ask the user exactly one question, with a recommendation, e.g. "Will there be more cost types beyond these 3? Yes → cost-lines table now (Recommended — invoices has added cost columns in 3 separate migrations); No → column is fine." This is the one case where the skill asks instead of deciding.
• Internal code shape — cheap to refactor later. With evidence → note, not blocker. Without evidence → don't ask; the simple version stands, say so in one line.
• Scale — a finding backed by real volumes is a risk (goes in Risks); one without numbers is a guess — measure or cut it.

If the plan also reveals the existing code already has the bad shape (e.g. invoices already has 7 cost_* columns), name it — but moving existing data is a separate piece of work with its own backfill, never silently folded into this plan.

If nothing here yields a finding, one line: "Shape holds — <why>."

3. Alternatives — only when real

Is there a materially different way to achieve the same goal — not a cosmetic variation? A different layer to change (shared function vs. per-caller), a reuse of something already in the codebase instead of new code, a simpler mechanism that covers the actual requirement, a native/platform feature the plan reinvents.

If yes: present 1–2, each with its honest trade-off, and recommend. If the plan is clearly the right approach, write one line saying so and move on — do not invent alternatives to populate a list.

4. Red-team — what breaks this?

Attack the plan as an adversary who wants it to fail in production:

• Edge cases the plan's happy path ignores (empty, null, concurrent, huge, first-run, retried).
• Blast radius — the sibling caller / dependent / consumer the plan forgot. If it touches a shared function, does it fix the root cause or just the one path named? Who else calls it?
• Safety — multi-tenant isolation, data loss, security, migration reversibility, money/ledger invariants.
• Hidden coupling — ordering, caching, queue/worker code that must be restarted, config that won't reload.
• Scope drift — is it over-built (abstractions/deps nobody asked for) or under-built (a shortcut with an unnamed ceiling)?

5. Verdict

Close with a clear call — no hedging:

• ✅ Proceed — sound as-is. Name the one thing to keep an eye on (there's always one).
• 🔧 Proceed with changes — fundamentally right, but these specific fixes must land first. List them, smallest-impactful first.
• 🛑 Reconsider — a load-bearing assumption is false/unverified, or a better approach exists. State the single most important reason and the recommended next step.

Output shape

Keep it skimmable — this is a decision aid, not an essay. Roughly:

## Plan validation

**Assumptions**
- ✅ <assumption> — verified: <how / what you found>
- ⚠️ <assumption> — UNVERIFIED: <what you'd need to check>
- ❌ <assumption> — false: <the reality>

**Design horizon**  (or: "Shape holds — <why>")
- <Nth-one / extensibility finding> — evidence: <migrations / file:line / counts> — <block / note>
- Scale: <table> has <N> rows, +<M>/month → <concern or "fine">
- ❓ <one question for the user, with recommendation> (only for data/API shape without evidence)

**Alternatives**  (or: "None materially better — the plan's approach is right because …")
- <Approach B>: <trade-off>. <recommend / not>

**Risks**
- <concrete failure mode> — <where / why> — <fix or watch>

**Verdict: ✅ / 🔧 / 🛑** — <one-line call + the single highest-value change or the one thing to watch>

Guardrails

• Verify from ground truth, not the plan text. A finding you can't back with a file, a schema, a query, or a real code path is a guess — label it as one or cut it.
• Restraint gate applies to every pass. Empty is allowed. "Nothing false here," "no better approach," "no new risk" are real results when true.
• Don't rewrite the plan. Surface findings and a verdict; let the author (Claude or the user) decide what to change. If asked to fix, that's a separate step.
• Concrete over comprehensive. Name the caller, cite the column, quote the line. Vague "consider performance implications" advice is noise.