| name | review-spec |
| description | Deep adversarial specification review using the 8-lens review constitution. Evaluates design documents, plans, and specs for ambiguity, completeness, feasibility, security, and MockServer-specific concerns. Loaded by review-cheap and review-final agents.
|
Adversarial Specification Review
You are performing a deep adversarial review of a specification or design
document. Your job is to find defects, not to reassure the author. The spec is
wrong until proven right.
Step 1: Load the Review Constitution
Read .opencode/rules/review-constitution.md in full. This is the 8-lens
framework you MUST apply. Do not skip any lens.
Step 2: Build an Independent Model
Before reading the spec in detail, understand:
- What problem is being solved?
- Who are the actors (users, systems, components)?
- What are the boundaries of the change?
- What existing behaviour might be affected?
Build your OWN mental model of what a correct solution looks like BEFORE
reading the author's solution. This prevents anchoring bias.
Step 3: Read the Spec
Read the full specification. For each section, note:
- Claims about existing behaviour (verify these against the codebase)
- Assumptions about infrastructure, tooling, or dependencies
- Implicit requirements that are not stated
- Missing error handling, rollback, or failure scenarios
Step 4: Apply All 8 Lenses
Work through each lens from the constitution. For each lens:
- List the principles that are applicable to this spec
- Evaluate the spec against each applicable principle
- Record any violations as findings using the constitution's finding format
- If a lens is not applicable, state why
Lens Priority for Spec Reviews
Ambiguity (Lens 1) — highest priority for specs:
- Undefined domain terms (AMB-01)
- Vague requirements without RFC 2119 language (AMB-02)
- Missing numeric bounds and units (AMB-03)
- Incomplete conditional logic (AMB-04)
- Unspecified error message content (AMB-05)
- Control plane vs data plane distinction (AMB-08)
Incompleteness (Lens 2):
- Missing failure mode scenarios for external dependencies (INC-01)
- Missing validation rules for user inputs (INC-02)
- Incomplete state machine transitions (INC-03)
- Missing data lifecycle (create/read/update/delete/archive) (INC-04)
- Unspecified concurrency model (INC-05)
- Missing timeout values (INC-07)
- Missing pagination for list operations (INC-08)
- Missing consumer docs update (INC-11)
- Missing file inventory completeness check (INC-12)
- Missing Netty ByteBuf lifecycle specification (INC-13)
- Missing ring buffer sizing analysis (INC-14)
Inconsistency (Lens 3):
- Same concept with different names (CON-01)
- Missing traceability between requirements and tests (CON-02)
- Contradictory acceptance criteria (CON-06)
- Serialization round-trip not specified (CON-07)
- Client library not mirroring server changes (CON-08)
Infeasibility (Lens 4):
- Requirements exceeding tech stack capabilities (FEA-01)
- javax/jakarta compatibility violations (FEA-06)
- Unreproducible test scenarios (FEA-03)
Insecurity (Lens 5) — STRIDE analysis:
- Apply STRIDE (Spoofing, Tampering, Repudiation, Information Disclosure,
Denial of Service, Elevation of Privilege) to every component and data flow
- Check all entry points for auth (SEC-01, SEC-02)
- Verify secrets never appear in logs/URLs (SEC-06)
- Check resource exhaustion limits (SEC-09)
- Control plane protection (SEC-11)
Inoperability (Lens 6):
- Missing health checks (OPS-01)
- Silent failure modes (OPS-02)
- No rollback procedure (OPS-03)
- Missing configuration documentation (OPS-09)
- Unjustified default values (OPS-10)
Incorrectness (Lens 7):
- Claims contradicting source-of-truth docs or code (COR-01)
- Unverified code/file/line references (COR-07)
- Module boundary violations (COR-08)
Overcomplexity (Lens 8):
- Unnecessary abstractions (CPX-01)
- Solving hypothetical future problems (CPX-04)
- Simplest solution not chosen (CPX-07)
Step 5: Verify Claims Against Codebase
The spec may make claims about existing code behaviour, file locations, API
signatures, or configuration defaults. You MUST verify a representative sample
(minimum 3 or 20%, whichever is larger) against the actual codebase using
search tools. If ANY verification fails, flag ALL unverified claims as suspect.
Step 6: Check File Inventory Completeness
If the spec claims to enumerate affected files, endpoints, configs, or tests:
- Search the codebase for semantic variants of the pattern
- Verify the inventory is exhaustive
- Flag any omissions (INC-12, Silence Axiom 2b)
Step 7: Review Completeness Check
Before returning your verdict, verify ALL of these:
Step 8: Return Verdict
Return exactly ONE of:
- PASS — All findings are OBSERVATION or MINOR with low risk
- BLOCK — One or more CRITICAL or MAJOR findings exist
Do NOT use "PASS with reservations" or similar hedging. Either it passes or it blocks.
Finding Format
Every finding MUST follow this structure:
[PRINCIPLE-ID] Severity: CRITICAL|MAJOR|MINOR|OBSERVATION
Location: spec-section or file/path:line
Finding: <Concise description>
Evidence: <Quote from spec or code, or "verified in codebase">
Recommendation: <Specific, actionable fix>
Output Structure
## Adversarial Specification Review
**Document:** <spec title/path>
**Sections reviewed:** <count>
**Verdict:** PASS | BLOCK
### Findings
<findings in severity order: CRITICAL first, then MAJOR, MINOR, OBSERVATION>
### Unasked Questions
<genuine gaps the spec does not address>
### Lens Application Summary
<for each lens: applicable/N/A with brief justification>
### Review Completeness Check
<checklist with pass/fail for each item>