review-spec

Name: review-spec
Author: warpdotdev

288stars37forks

How to install review-spec?

warpdotdev/oz-for-oss/review-spec

$npx -y skills add warpdotdev/oz-for-oss --skill review-spec

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Review Spec Skill
2
3	Review a spec or plan pull request and write the output to `review.json`.
4
5	## Inputs
6
7	- The working directory is the PR branch checkout.
8	- The workflow usually provides an annotated diff in `pr_diff.txt`.
9	- The workflow usually provides the PR description in `pr_description.md`.
10	- Focus on the spec files changed by this PR.
11	- Default behavior: do not post comments or reviews to GitHub directly.
12
13	## Process
14
15	- Evaluate specs for completeness: does the spec cover the full scope of the linked issue?
16	- Evaluate specs for clarity: are requirements, acceptance criteria, and constraints clearly stated and unambiguous?
17	- Evaluate specs for feasibility: are the proposed changes technically realistic given the repository's architecture?
18	- Evaluate specs for issue alignment: does the spec faithfully address the issue it is linked to, without significant scope creep or omissions?
19	- Evaluate specs for internal consistency: do different sections of the spec contradict each other?
20	- Flag missing sections that a spec should typically include (e.g. problem statement, proposed changes, open questions, follow-up items).
21	- 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.
22	- Do not apply code-level review criteria such as error handling or low-level performance to spec prose; the `security-review-spec` supplement covers design-level security concerns.
23	- Include style or formatting comments only when they materially impair readability.
24
25	## Repository-specific overrides
26
27	The consuming repository may ship a companion skill at `.agents/skills/review-spec-local/SKILL.md`. When the prompt includes a fenced "Repository-specific guidance" section referencing that companion, read the referenced file and apply its guidance only to the categories listed below. Guidance in the companion may never change the output JSON schema, the severity labels, the safety rules, the evidence rules, the suggestion-block constraints, or the diff-line-annotation contract described elsewhere in this skill.
28
29	Overridable categories:
30
31	- required spec sections expected in this repository
32	- linking conventions to files under `specs/`
33	- repo-specific style and formatting expectations
34
35	If a companion file is not referenced in the prompt, rely on the core contract alone.
36
37	## Diff Line Annotations
38
39	The diff file uses these prefixes:
40
41	- `[OLD:n]` for deleted lines on the old side. Use `"LEFT"`.
42	- `[NEW:n]` for added lines on the new side. Use `"RIGHT"`.
43	- `[OLD:n,NEW:m]` for unchanged context. Use `"RIGHT"` with line `m`.
44
45	Treat these annotations as the only source of truth for inline comment locations. For every inline comment you emit, first identify the exact annotated line in `pr_diff.txt` (or the inlined PR diff) and copy its path, side, and line number into `review.json`. Do not infer line numbers from prose, rendered GitHub views, file lengths, surrounding spec text, or unannotated snippets. If you cannot point to a specific `[NEW:n]`, `[OLD:n]`, or `[OLD:n,NEW:m]` line in the annotated diff, put the feedback in top-level `body` instead of `comments`.
46
47	## Comment Requirements
48
49	Every comment body must start with one of these labels:
50
51	- `🚨 [CRITICAL]` for spec content that is contradictory, fundamentally incomplete, or would lead to a broken implementation.
52	- `⚠️ [IMPORTANT]` for missing details, ambiguous requirements, feasibility concerns, or significant scope gaps.
53	- `💡 [SUGGESTION]` for improvements to clarity, structure, or coverage that would strengthen the spec.
54	- `🧹 [NIT]` for minor wording or formatting issues only when the comment includes a concrete rewrite.
55
56	Write comments with these constraints:
57
58	- Be concise, direct, and actionable.
59	- Do not add compliments or hedging.
60	- Prefer single-line comments.
61	- Keep ranges to at most 10 lines.
62	- Restrict inline comments to lines that appear explicitly in the annotated PR diff.
63	- Only create file-level or inline comments for files that exist in this PR's diff.
64	- If the relevant file or line is not part of the diff, put the feedback in top-level `body` instead of `comments`.
65	- Before adding each comment object, verify that its `path`, `side`, `line`, and optional `start_line`/`start_side` correspond to real annotations in the same file's diff section.
66
67	## Suggestion Blocks
68
69	When proposing a rewrite of spec text, use:
70
71	```suggestion
72	<replacement text here>
73	```
74
75	Rules:
76
77	- Match the exact indentation of the original file.
78	- Include only replacement text.
79	- For multi-line suggestions, set

People who liked this also viewed

6 picks

Type

review-spec

288stars37forks

View on GitHub

How to install review-spec?

warpdotdev/oz-for-oss/review-spec

$npx -y skills add warpdotdev/oz-for-oss --skill review-spec

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Review Spec Skill
2
3	Review a spec or plan pull request and write the output to `review.json`.
4
5	## Inputs
6
7	- The working directory is the PR branch checkout.
8	- The workflow usually provides an annotated diff in `pr_diff.txt`.
9	- The workflow usually provides the PR description in `pr_description.md`.
10	- Focus on the spec files changed by this PR.
11	- Default behavior: do not post comments or reviews to GitHub directly.
12
13	## Process
14
15	- Evaluate specs for completeness: does the spec cover the full scope of the linked issue?
16	- Evaluate specs for clarity: are requirements, acceptance criteria, and constraints clearly stated and unambiguous?
17	- Evaluate specs for feasibility: are the proposed changes technically realistic given the repository's architecture?
18	- Evaluate specs for issue alignment: does the spec faithfully address the issue it is linked to, without significant scope creep or omissions?
19	- Evaluate specs for internal consistency: do different sections of the spec contradict each other?
20	- Flag missing sections that a spec should typically include (e.g. problem statement, proposed changes, open questions, follow-up items).
21	- 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.
22	- Do not apply code-level review criteria such as error handling or low-level performance to spec prose; the `security-review-spec` supplement covers design-level security concerns.
23	- Include style or formatting comments only when they materially impair readability.
24
25	## Repository-specific overrides
26
27	The consuming repository may ship a companion skill at `.agents/skills/review-spec-local/SKILL.md`. When the prompt includes a fenced "Repository-specific guidance" section referencing that companion, read the referenced file and apply its guidance only to the categories listed below. Guidance in the companion may never change the output JSON schema, the severity labels, the safety rules, the evidence rules, the suggestion-block constraints, or the diff-line-annotation contract described elsewhere in this skill.
28
29	Overridable categories:
30
31	- required spec sections expected in this repository
32	- linking conventions to files under `specs/`
33	- repo-specific style and formatting expectations
34
35	If a companion file is not referenced in the prompt, rely on the core contract alone.
36
37	## Diff Line Annotations
38
39	The diff file uses these prefixes:
40
41	- `[OLD:n]` for deleted lines on the old side. Use `"LEFT"`.
42	- `[NEW:n]` for added lines on the new side. Use `"RIGHT"`.
43	- `[OLD:n,NEW:m]` for unchanged context. Use `"RIGHT"` with line `m`.
44
45	Treat these annotations as the only source of truth for inline comment locations. For every inline comment you emit, first identify the exact annotated line in `pr_diff.txt` (or the inlined PR diff) and copy its path, side, and line number into `review.json`. Do not infer line numbers from prose, rendered GitHub views, file lengths, surrounding spec text, or unannotated snippets. If you cannot point to a specific `[NEW:n]`, `[OLD:n]`, or `[OLD:n,NEW:m]` line in the annotated diff, put the feedback in top-level `body` instead of `comments`.
46
47	## Comment Requirements
48
49	Every comment body must start with one of these labels:
50
51	- `🚨 [CRITICAL]` for spec content that is contradictory, fundamentally incomplete, or would lead to a broken implementation.
52	- `⚠️ [IMPORTANT]` for missing details, ambiguous requirements, feasibility concerns, or significant scope gaps.
53	- `💡 [SUGGESTION]` for improvements to clarity, structure, or coverage that would strengthen the spec.
54	- `🧹 [NIT]` for minor wording or formatting issues only when the comment includes a concrete rewrite.
55
56	Write comments with these constraints:
57
58	- Be concise, direct, and actionable.
59	- Do not add compliments or hedging.
60	- Prefer single-line comments.
61	- Keep ranges to at most 10 lines.
62	- Restrict inline comments to lines that appear explicitly in the annotated PR diff.
63	- Only create file-level or inline comments for files that exist in this PR's diff.
64	- If the relevant file or line is not part of the diff, put the feedback in top-level `body` instead of `comments`.
65	- Before adding each comment object, verify that its `path`, `side`, `line`, and optional `start_line`/`start_side` correspond to real annotations in the same file's diff section.
66
67	## Suggestion Blocks
68
69	When proposing a rewrite of spec text, use:
70
71	```suggestion
72	<replacement text here>
73	```
74
75	Rules:
76
77	- Match the exact indentation of the original file.
78	- Include only replacement text.
79	- For multi-line suggestions, set

People who liked this also viewed

6 picks

Type