Overview

spec-review performs an adversarial pre-approval review of a design document — a spec, design doc, RFC, ADR, or implementation plan. It hunts for the recurring gaps that otherwise surface late (or in production): missing bootstrap/ownership, misleading names, unconsidered scale, unstated assumptions, claims that don't match the code, missing failure handling, unexamined security surface, unjustified complexity, and incompleteness. Critically, it verifies claims against the actual codebase rather than trusting the prose, and it cites file:line evidence so every finding is grounded. It produces a findings report and a verdict; it never edits the document and never approves — that stays with the human reviewer and the author. Use it as the gate between writing a design and signing off on it.

When to activate

✅ A spec / design doc / RFC / ADR / implementation plan is about to be approved and you want gaps found first.
✅ A document author wants a critical pass before presenting their design for sign-off.
✅ An automated workflow needs a consistent pre-approval review step over design documents.