review-spec
Review proposed specifications for feasibility, gaps, and testability; not plans or code conformance.
SKILL.mdagent-plugins/skills/review-spec/SKILL.md
GitHubReview Specification
Review a proposed design or requirements document before it becomes an implementation contract. Return an evidence-backed readiness verdict without editing the document or creating a report file unless requested.
Route precisely
- Use this skill when the primary question is whether a proposed specification or design revision is sound. Related code may already exist; inspect it as context without turning this into a code review.
- Use
plan-reviewwhen the primary artifact is an ordered implementation plan. - Use
verify-implwhen the question is whether existing code satisfies an authoritative specification. - Use
review-archfor the structure of an existing system or a system-wide architecture decision. - Use
code-reviewfor changed code or a pull-request diff.
Establish the review contract
- Identify the exact spec revision or file and the user's stated goal. If neither a document nor its contents are available, request the missing artifact.
- Read applicable repository instructions, the requirements or issue that motivated the spec, and directly relevant architecture decisions. Treat missing or conflicting sources as review limits.
- Inspect only the code, interfaces, and configuration needed to verify material claims about the current system. Do not turn this into an unrelated repository audit.
- Separate explicit requirements, design decisions, assumptions, and open questions. An assumed business priority is not a fact.
For a specification targeting Go, read references/go-spec-checks.md. Apply its language and CLI checks only where the design uses those boundaries; keep the same readiness verdict and evidence rules.
Evaluate the spec
Check the dimensions that apply:
- Goal and scope: The proposed behavior and excluded cases are clear enough to implement consistently.
- Consistency: Requirements, examples, diagrams, interfaces, and acceptance criteria do not contradict each other or binding project decisions.
- Feasibility: Named symbols, dependencies, migrations, environments, and integration points exist or have a credible creation path.
- Boundaries: Ownership of data, authentication and authorization, trust boundaries, failure handling, retries, concurrency, and lifecycle rules are explicit where relevant.
- Testability: Each material obligation has an observable success or failure condition; numeric limits, defaults, ordering, and edge cases are specified when they affect behavior.
- Tradeoffs: The design's cost, complexity, performance, and operational consequences fit stated priorities. Flag unknown priorities as questions, not defects.
For every candidate concern, cite a spec section or exact excerpt and the requirement, code, or decision that makes it consequential. Check whether another part of the spec answers it before reporting it. Do not demand implementation detail that the project intentionally leaves to the implementer. Do not invent requirements to fill a template.
Classify and report
Use P0 for an immediate safety or irreversible-loss problem, P1 for a contradiction or gap likely to make implementation incorrect, P2 for a material ambiguity or maintainability risk, and P3 for a small improvement. Put an unresolved high-impact premise in Questions with the evidence needed to settle it.
Return:
- spec identity, goal, sources inspected, and limits;
READY,REVISE, orBLOCKEDwith a one-sentence reason (BLOCKEDmeans the artifact or essential evidence cannot be reviewed, not that the spec is poor);- confirmed findings ordered by priority, each with location, consequence, and smallest spec-level correction;
- requirements or decisions that are already sound and should survive revision;
- open questions that materially affect implementation.
Use READY only when no unresolved issue would make implementation unsafe or substantially ambiguous. A review verdict does not verify future code.