/plan-review-gate

name: plan-review-gate
description: "Use after saving a non-trivial plan or decision RFC when a fail-closed feasibility, completeness, and alignment review must block execution."
allowed-tools: Read Bash Grep Glob
user-invocable: false

Spec Review Gate

**Core principle:** No execution plan or decision RFC reaches the user without surviving adversarial scrutiny. No leniency. "Close enough" is FAIL. A structurally neat but repo-wrong plan is FAIL.

**How it works:** This skill runs inline in the calling agent's context (no subagents). The calling LLM acts as an independent auditor, reads the saved artifact, and checks it against 3 criteria using Read/Grep/Glob. The value is fail-closed blocking and adversarial framing, not reviewer isolation — keep the auditor posture, but do not claim independence the gate doesn't have.

When to Skip

**Skip when artifact is truly trivial:** Single-file fix, copy edit, or config tweak with <3 changes and no architecture choice → return `SPEC_GATE_PASS` immediately.

The 3 Checks (Run in Sequence)

Check 1: Feasibility — Can this be executed against the real codebase?

Run these verifications using Read/Grep/Glob:

| Criterion | How to verify | Blocking if | |-----------|--------------|-------------| | Artifact file exists on disk | `Glob(pattern="{plan_file_path}")` where plan_file_path is the path from the calling agent's context | Returns 0 matches | | File paths exist | `Glob(pattern="{path}")` for every referenced file | Any path returns 0 matches and doesn't exist | | Codebase reality check is present | Read artifact for `Codebase Reality Check` | Non-trivial plan omits repo-grounded verification of existing code | | Dependency ordering | Read plan phases — do later phases depend on earlier ones only? | Circular or forward-reference dependencies | | Technical approach matches codebase | Read 1-2 existing files in the affected area | Proposed patterns/libs differ from what codebase actually uses | | No unstated infra assumptions | Read plan for external services, env vars, DBs | Plan silently assumes infra that doesn't exist | | No invented or unverified file/module assumptions | Compare claimed touched surfaces to repo reality | Artifact presents guessed files/modules as verified facts | | Plan mode fits the task | Read request + artifact: `direct`, `execution_plan`, or `decision_rfc` | Request changes ≥3 files or any contract/schema/auth surface while mode is `direct`; or request asks for a decision between alternatives and mode is not `decision_rfc` | | Verification rigor fits risk | Check `verification_rigor` against the requested work | Critical-path work is missing `critical_path` rigor or claims proof it never defined |

**Critical-path work** = auth, payment, data-destructive operations, migrations, or work the user labeled critical.

Check 2: Completeness — Does it cover the full request?

Read the user's original request and compare against the plan:

| Criterion | How to verify | Blocking if | |-----------|--------------|-------------| | All requirements mapped | List each sentence of the user request; cite the plan item covering it | Any user requirement has no corresponding plan item | | Verification steps defined | For each plan item, find its named test, command, or checklist | Any change has no way to verify it worked | | Edge cases addressed | For each input surface the plan touches, find its empty, invalid, and failure case | An input surface's empty, invalid, or failure case is neither named nor covered by an explicit "why none applies" statement | | Cross-file integration | Trace each touched surface to the callers/importers the plan names | missing touched surfaces or integration points | | Plan-vs-code gaps surfaced | Read the artifact for the mismatch table; spot-check one claim against the code | A non-trivial plan omits the concrete mismatch table or hides contradictions with current code | | Assumption ledger is honest | Read each important claim for its classification tag | Important claims are not classified as `proven_by_code`, `inferred`, or `needs_user_confirmation` | | Phase dependency map is present | Read each phase for its depends-on/enables statements | Non-trivial phases do not say what they depend on or what they enable | | Durable Decisions present for multi-phase plans | For multi-phase plans, read for a foundational-decisions section | A multi-phase plan omits foundational decisions (routes, schema, models, auth, third-party boundaries) that all phases should reference | | Decision-grade content present when needed | For `decision_rfc`, read for alternatives, drawbacks, and references sections | A `decision_rfc` is missing alternatives, drawbacks, or references | | Critical-path spec present when needed | For `critical_path`, read for each of the five required sections | A `critical_path` artifact is missing behavior contract, edge-case catalog, provable properties, purity boundary, or verification strategy |

Check 3: Scope & Alignment — Is it right-sized and faithful?

| Criterion | How to verify | Blocking if | |-----------|--------------|-------------| | Matches user request | Re-read the request; diff its ask against the plan's stated goal | Plan solves different problem or adds unrequested features | | No scope creep | For each plan item, name the requirement it serves | Extra abstractions, refactoring, or features beyond the request | | No under-scoping | List the request's direct implications; find each in the plan | Direct implications of the request are omitted | | Execution order is real | Walk the phases in order; check each prerequisite exists in an earlier phase | wrong execution order or missing prerequisites | | Complexity proportional | For each new file, abstraction, or dependency, cite the requirement row that needs it | The plan introduces a file, abstraction, or dependency that no requirement row maps to | | Defaults are framed honestly | Check each recommended