review-spec

name	review-spec
description	Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish. Use when reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub.

Review Spec Skill

Review a spec or plan pull request and write the output to review.json.

Inputs

• The working directory is the PR branch checkout.
• The workflow usually provides an annotated diff in pr_diff.txt.
• The workflow usually provides the PR description in pr_description.md.
• Focus on the spec files changed by this PR.
• Default behavior: do not post comments or reviews to GitHub directly.

Process

• Evaluate specs for completeness: does the spec cover the full scope of the linked issue?
• Evaluate specs for clarity: are requirements, acceptance criteria, and constraints clearly stated and unambiguous?
• Evaluate specs for feasibility: are the proposed changes technically realistic given the repository's architecture?
• Evaluate specs for issue alignment: does the spec faithfully address the issue it is linked to, without significant scope creep or omissions?
• Evaluate specs for internal consistency: do different sections of the spec contradict each other?
• Flag missing sections that a spec should typically include (e.g. problem statement, proposed changes, open questions, follow-up items).
• Always apply the repository's local security-review-spec skill as a supplemental high-level security pass on spec PRs. Fold any security findings into the same review.json produced by this review rather than emitting a separate output.
• Do not apply code-level review criteria such as error handling or low-level performance to spec prose; the supplement covers design-level security concerns.