# Specification Review > Independently review a specification, RFC, requirements set, behavioral contract, or decision-bearing proposal for contradictions, ambiguity, hidden decisions, unsupported claims, missing boundaries or failure behavior, and wording loopholes before implementation or adoption. Work read-only and return prioritized findings and readiness limits; route architecture fitness, product evidence, domain meaning, editorial quality, and code changes to their owners. - Skill: `zhuochun/specification-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add zhuochun/specification-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/zhuochun/specification-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: zhuochun (https://skillmd.com/u/zhuochun) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zhuochun/specification-review --- # Specification Review Judge whether a specification makes consequential intent clear enough for its next use. Find disagreements before they propagate; do not become the author. ## Preserve reviewer independence and authority - Work read-only. Do not rewrite the artifact, accept its decisions, authorize implementation, approve adoption, or resolve findings unless the user separately authorizes that action. - Pin the exact artifact or snapshot, canonical sources, intended next use, accountable owner, affected parties, and cost of wrong interpretation. - Recover intent independently from the originating request, current behavior, accepted decisions, constraints, and evidence. Treat the producer's rationale as a claim to inspect, not the review oracle. - Separate specification integrity from subject-matter correctness. Expose a missing product, domain, architecture, contract, security, data, legal, or operational decision, then route that judgment to its owner. - Independence requires fresh judgment, direct artifact inspection, distinct criteria or evidence, and permission to reject—not a second label alone. - Match review depth to ambiguity, propagation, consequence, reversibility, feedback delay, and coordination boundaries. Let a clear, cheap, reversible action bypass formal specification review. ## Clarify without co-authoring - Inspect the artifact and discoverable evidence before asking its owner. - Inspect only decision-changing evidence. Stop when more context would widen into product, architecture, or system assessment; state the limit and route it. - Ask only questions that can change a finding, interpretation, readiness, or route. Batch independent low-sensitivity questions; serialize dependent ones. - When the user asks to grill, challenge, or stress-test the specification, deepen counterexample and loophole search. Do not negotiate findings or coach the author toward answers that make the review pass. - Treat unanswered consequential questions as findings or explicit limitations. Never invent intent to produce a clean result. ## Review workflow 1. **Pin the review contract.** Record the artifact identity, review scope, authoritative inputs, intended audience or consumer, next decision or action, non-goals, and consequence of error. Exclude unrelated document quality. 2. **Recover the proposition.** State the asserted outcome, problem, desired and preserved behavior, accepted decisions, constraints, evidence claims, and unresolved questions. Flag silent narrowing to an easier proxy. 3. **Map claims and authority.** Distinguish confirmed, inferred, assumed, proposed, and unresolved material. Identify undefined normative terms, ownerless decisions, unsupported certainty, stale sources, and competing authorities. 4. **Trace interpretations.** Follow important inputs, decisions, state, effects, outputs, consumers, and lifecycle obligations. Show where reasonable readers could derive incompatible outcomes. 5. **Challenge coherence.** Find contradictions, circular definitions, hidden dependencies, incompatible constraints, omitted prerequisites, duplicate authority, and claims that rely on an unstated sequence or environment. 6. **Probe boundaries and failures.** Use positive and negative cases, then vary identity, permission, state, ordering, timing, repetition, limits, partial failure, recovery, compatibility, and retirement. When the artifact changes attacker-controlled input, protected data or effects, identity, secrets, dependencies, tenant boundaries, privilege, or security defaults, also test plausible abuse, direct-entry, fallback, and control-unavailable paths. Seek wording-compliant failures without pretending this integrity review is a complete security assessment. 7. **Check evaluability.** Determine whether acceptance or decision claims are observable and falsifiable enough for the next owner. Separate missing oracles from missing evidence methods; route method design to verification strategy and execution to `software-verification`. 8. **Route specialist judgment.** Keep product value and customer evidence with `product-opportunity-discovery`; domain meaning with `domain-modeling`; architecture fitness with `architecture-risk-evaluation`; shared contract compatibility with `software-contract-evolution`; threat, security requirement, secure-default, and control-ownership decisions with `software-security-design`; and accountable choice closure with `decision-facilitation`. 9. **Prioritize findings.** Rank by consequence, propagation, reversibility, and confidence. Give each explicit confidence, the tightest locator, conflicting interpretations or counterexample, impact, and smallest credible repair direction or receiving owner. 10. **Report the outcome.** Lead with findings, then questions, assumptions, evidence inspected, routed judgments, and residual limits. Return `ready for next accountable use`, `ready with owned follow-through`, or `not ready`. A clean review is not approval or certification. ## Calibrate findings - **Blocker:** The artifact cannot responsibly support its named next use because a consequential contradiction, missing decision, or unbounded interpretation can propagate material harm. - **Major:** A realistic ambiguity, omission, unsupported claim, or loophole can produce materially different behavior or a costly downstream correction. - **Minor:** A bounded defect can mislead a reader or weaken traceability but is unlikely to redirect the core outcome. - **Question or limitation:** Evidence is insufficient to claim a defect. State the decision-changing uncertainty without inflating severity. - Keep a local, cheap, reversible gap at Minor even when implementation pauses; stopping alone does not make it Major or Blocker. - Lower confidence instead of raising severity for a merely plausible concern. Phrase questions as questions. ## Compose with artifact producers - Use `software-change-specification` to create or materially revise an accepted software behavior contract. Review its fixed candidate here without replaying the producer workflow. - Use the relevant product, domain, architecture, contract, or decision skill to produce or revise owned content. A reviewer recommends repairs but does not make them. - Use `technical-writing` for tutorials, how-to guides, explanations, reference, procedures, articles, editorial quality, and representative-reader function. A decision-bearing document remains reviewable here only for its normative specification claims. - Use `code-review` for a working tree, commit, branch, pull request, migration, configuration change, or other implemented candidate. ## Quality gates - The exact artifact, authoritative inputs, scope, and next use are reproducible. - Findings arise from demonstrated contradiction, competing interpretation, counterexample, unsupported claim, missing authority, or consequential gap. - Each actionable finding names impact and a repair direction or receiving owner without rewriting the artifact. - Subject-matter uncertainty remains visible and routed rather than converted into reviewer preference. - A material security surface either traces to accepted `SEC-*` requirements and an accountable owner or remains an explicit readiness limitation. - The outcome distinguishes artifact readiness from accountable acceptance, implementation authority, and later verification. ## Reject review theater - Length, polish, templates, diagrams, and examples do not prove preserved intent. Missing sections or style preferences matter only when they cause a demonstrated failure. - Do not reward precision that encodes the wrong goal or acceptance wording that can pass while the intended outcome fails. - Do not add unrequested features, reopen accepted decisions without evidence, or widen a bounded review into product discovery or architecture assessment. - Repetition is not independence. A clean second pass with the same framing and evidence does not certify the artifact.