review-spec

# 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: 1. List the principles that are applicable to this spec 2. Evaluate the spec against each applicable principle 3. Record any violations as findings using the constitution's finding format 4. 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: 1. Search the codebase for semantic variants of the pattern 2. Verify the inventory is exhaustive 3. 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 ```markdown ## 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> ```