speckit-review
Skill3 starsChanged 5 days agoApache-2.0View on GitHub
Review the implemented branch before its pull request, with a fresh context, and act on the findings
In this repository16 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- speckit-analyzeSkill
- speckit-bdd-checkSkill
- speckit-bdd-featuresSkill
- speckit-buildSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-designSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Every finding is fixed or answered, the fixes are committed, and the outcome is written down for the pull request.
- Very specific: line 28
Consider the user input before proceeding, if it is not empty.
- Very specific: line 34
Run .specify/scripts/bash/check-prerequisites.sh --json from the repository root and take FEATURE_DIR from it.
- Distinctive: line 76
Wait for it. Do not review in parallel yourself, and do not answer its findings before reading them.
- Very specific: line 80
Read review.md. Then, in this order:
- Very specific: line 100
One more round: When any blocking finding was fixed, spawn the reviewer again on the fix commits only (<sha before the fixes>...HEAD) with …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review the branch before the pull request
The code /speckit-implement wrote is reviewed here, in the worktree, before anything is pushed: by
a reviewer with a fresh context, against the repository's own rules and the pr-review checklists.
Every finding is fixed or answered, the fixes are committed, and the outcome is written down for the
pull request. A pull request raised after this already carries a review, so the time between push
and merge is CI's alone.
The reviewer is not this session. A session that wrote the code knows what it meant and reads that instead of what is there; so the review runs in a subagent that is given the spec, the plan and the branch, and nothing of this conversation.
User input
$ARGUMENTSConsider the user input before proceeding, if it is not empty. --base <branch> names the base when
the rule below would pick the wrong one. --skip <reason> records in the completion report that the
review was skipped and why, and stops here.
Setup
- Run
.specify/scripts/bash/check-prerequisites.sh --jsonfrom the repository root and takeFEATURE_DIRfrom it. All paths absolute. - The branch must be committed.
git status --porcelainmust print nothing. If it does, stop and say what is uncommitted: the review reads commits, and the pull request will carry only commits, so an uncommitted change is either unfinished work or a stray file, and either is the implementer's to settle first. - The base is the branch the pull request will target:
main, unless this branch was cut from a feature branch that is not yet merged, in which case that branch. Take--basewhen given.git merge-base <base> HEADmust resolve, and<base>...HEADmust not be empty; an empty range means there is nothing to review, so say so and stop. The reviewer must exist. The
pr-reviewskill is listed aspr-review:pr-reviewwhen the plugin is installed, or aspr-reviewfrom a project or personal skill directory. When neither is listed, stop and say how to install it:/plugin marketplace add thinkmorestupidless/ankka-marketplace /plugin install pr-review@ankkaor, before a release carries it, start the session with
claude --plugin-dir <ankka checkout>/marketplace/plugins/pr-review. Do not substitute a lesser review silently: a hook that reports a review it did not run is worse than no hook.
The review
Spawn one subagent (the Agent tool, a general-purpose agent, a fresh context) with this brief, the placeholders filled in:
Load the skill pr-review (listed as pr-review:pr-review when installed as a plugin) and follow it
to review the commit range <base>...HEAD in the repository at <worktree path>. You are the reviewer,
not the author: nothing of the implementation session is available to you, on purpose. The change
has no pull request yet; its description is <FEATURE_DIR>/spec.md and <FEATURE_DIR>/plan.md, and
<FEATURE_DIR>/tasks.md says what was meant to be done. Review what the diff does against what they
say, as well as against the skill's checklists. The feature is done only when its documentation
shows every sample in every language the project supports: where the repository states that rule (a
REVIEW.md, a contributing page, a docs check), hold the diff to it, and report a page, a sample or a
limitations entry a supported language is missing as a finding, blocking when the rule says so.
Write the report, in the skill's template, to <FEATURE_DIR>/review.md, and reply with the verdict
line and the number of findings at each severity. Post nothing anywhere.Wait for it. Do not review in parallel yourself, and do not answer its findings before reading them.
Acting on the findings
Read review.md. Then, in this order:
- Blocking. Fix every one. If a blocking finding is wrong in your judgement, do not argue it away: stop, show the finding and your reason, and let the user decide.
- Should fix. Fix each, or decline it with a reason that would satisfy the reviewer. "Out of scope" is a reason only when the spec says so.
- Questions. Answer each under the finding. An answer that amounts to "yes, that is a defect" becomes a fix.
- Nits. Fix when a minute's work; otherwise leave them, noted.
- Out of scope. Change nothing; leave the note for the pull request.
Fixes are commits, grouped by concern (the foundation first: types and shared code, then the code that uses them, then tests), each commit's message naming what it resolves. Never one commit for everything; never a fix without its test when the finding was about behaviour. Run the checks implement ran on the files the fixes touch, and the formatter.
Under each finding in review.md, append one line: Resolved: <what changed>, <short sha>,
Declined: <reason>, Answered: <answer> or Left: nit. Commit review.md with the last fix, or
alone when nothing was fixed; the message is "Review before the pull request: N findings, M fixed".
One more round. When any blocking finding was fixed, spawn the reviewer again on the fix commits
only (<sha before the fixes>...HEAD) with the same brief plus: "This is a second round. The
previous report is at <FEATURE_DIR>/review.md; review the fixes, and say for each resolution whether
it holds." Act on what it finds the same way, once. A third round is a conversation for the user:
stop and show both reports.
Report
Print, for the implement session's completion report and for the pull request body:
Review before push: pr-review on <base>...HEAD, <verdict after the fixes>.
Found: B blocking, S should-fix, N nits, Q questions. Fixed: F in K commits. Declined: D (reasons in review.md). Left: L nits.
Report: <FEATURE_DIR>/review.mdThe pull request body carries these lines under its "Checks run". The verdict there is the reviewer's after the fixes, never the implementer's own.
Changing or replacing this review
This hook is one entry in .specify/extensions.yml under hooks.after_implement, and its only
coupling to pr-review is the brief above.
- No review: set
enabled: falseon the entry, and say so in the pull request. - Another reviewer: point the entry's
commandat your own command or skill. This file is the shape to copy: a fresh context, every finding acted on, the outcome recorded. - The same reviewer, your rules:
pr-reviewreads the repository'sCLAUDE.mdand rule files first and lets them overrule its checklists; applies aREVIEW.mdas the repository's own review checklist, whose## pr-reviewsection can skip bundled checklists or load further skills; and loads a project or personal skill namedpr-review-<language>in place of the bundled one. Nothing in this file needs to change for any of that.
Done when
review.mdin the feature directory holds the report with a resolution line under every finding- Every blocking and should-fix finding is fixed, or declined with its reason; the fixes are committed and checked
- Every language the feature reaches has its documentation sample, or the report says which is missing and why
- The tree is clean and the three report lines were printed
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

