review-spec - SKILL.md Agent Skill

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)

Structure Expectation

Well-formed specs follow the Pyramid Principle with progressive disclosure (.opencode/rules/documentation-style.md): an executive summary / outcome first, then context, then detailed requirements — exactly the shape of .opencode/skills/ideate/spec-template.md. If a spec buries its conclusion, introduces detail before its context, or has no top-level takeaway, record it as an OBSERVATION (it impairs reviewability) — not a blocking finding unless it also causes a genuine ambiguity or incompleteness defect under the lenses above.

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:

Every lens applied (or explicitly marked N/A with justification)
Every finding has a specific section reference from the spec
Every finding has a concrete, actionable recommendation
Findings classified by severity (CRITICAL, MAJOR, MINOR, OBSERVATION)
No false reassurance language ("looks good", "seems fine", "probably works")
STRIDE analysis covers every component/data flow
Unasked questions section identifies genuine gaps
File inventory includes consumer docs, client library, and integration layer when applicable
Representative sample of code/file claims verified against codebase

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>