review-pr
Skill836 starsChanged 19 days agoApache-2.0View on GitHub
Review someone else's gcx pull request, produce a ranked report with a verdict, and optionally post it to GitHub as line-anchored inline comments. Covers what to report, in what order, when to stop, how to rank over-engineering findings, how to judge whether a large diff is justified, and how to turn the report into review comments with an APPROVE/COMMENT/REQUEST_CHANGES recommendation. Trigger on "review this PR", "review #NNNN", "code review this branch", "is this diff over-engineered", "post the review", "add review comments to this PR". NOT for self-review before pushing your own work — use contribute for that.
185 other projects use a version of this.
Adopted by
Most recently taken up by
- torrust/torrust-trackertheir own version, first seen Nov 16, 2026
- Wendor/teapod-streamtheir own version, first seen Nov 16, 2026
- testcontainers/testcontainers-javatheir own version, first seen Nov 16, 2026
- hotcodepush-team/skillstheir own version, first seen Nov 16, 2026
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- ayoubben18/ab-methodtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use diagnose-ci-failures, review-delta and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
zerx-labSkilldiagnose-ci-failures
Diagnose CI failures for a PR using the GitHub CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate PR build failures.
Also in 3 projects that use this
n24q02mSkillreview-delta
Review only changes since last commit using impact analysis. Token-efficient delta review with automatic blast-radius detection.
Also in 3 projects that use this
GeiserXSkilldocs-loop
Use when the user asks to audit docs, check documentation for stale claims, or verify docs against the code.
Also in 3 projects that use this
GeiserXSkillfull-loop
Drive a repository to done with sergio-loop, then keep improving it with refine-loop at a descending theta. Use only when the user explicitly invokes full-loop.
Also in 3 projects that use this
n24q02mSkillbuild-graph
Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.
Also in 3 projects that use this
- +7 more from GeiserX
Other versions185 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 185
- denoland/deno★ 109ksame name
- ToolJet/ToolJet★ 41ksame name
- remix-run/remix★ 33ksame name
- tirth8205/code-review-graph★ 33ksame name
- alpinejs/alpine★ 32ksame name
- nrwl/nx★ 29ksame name
- PrefectHQ/fastmcp★ 29ksame name
- jlowin/fastmcp★ 29ksame name
- livewire/livewire★ 24ksame name
- microsoft/fluentui★ 20ksame name
175 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- contributeSkill
- create-rfcSkill
- generate-slideSkill
- propose-featureSkill
- releaseSkill
- review-rfcSkill
- update-rfcSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 11 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 178 edited versions we read keep these.
11
Distinctive
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 8
Use this skill to review work you did not write.
- Distinctive: line 66
Do that even when the argument for them is strong.
- Distinctive: line 78
Use bold text for headings in the report, not markdown headings.
- Distinctive: line 143
Drop what you could not establish: Do not label it unverified.
- Distinctive: line 192
After the report, offer to post it to the PR as inline comments.
- Very specific: line 228
Keep the endpoint first, unquoted, and followed by -X POST, matching the review permission in .claude/settings.json.
- Distinctive: line 255
Never paste report prose into a thread.
- Distinctive: line 258
Write two to four sentences.
- Distinctive: line 260
Start with a bold label that says what the author must do.
- Very specific: line 263
Use a suggestion block for any concrete one-line change.
- Distinctive: line 267
Do not open with a compliment.
- Very specific: line 270
When one finding covers several sites, anchor it at one site and name the others in the text (also flow.go:160, gcom.go:145).
- Very specific: line 301
Only label a comment required when it sits in section 2 of the report.
- Distinctive: line 306
Write the report and the comments in plain English:
- Distinctive: line 312
Avoid phrases or terms that hyphenate words together.
“Common” is measured: kept by at least 6 in 10 of the 178 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reviewing a gcx pull request
Use this skill to review work you did not write. It owns the report: what goes in it, in what order, and when to stop.
It defines no checks of its own. Run the checks where they already live:
.agents/skills/contribute/references/self-review.md. Read Evidence discipline first. It sets what a finding may conclude. Then run the triggers that fire for the diff. T12 is the over-engineering rubric. T5 covers code that repeats something the repo already has.- AGENTS.md, for the compliance hierarchy. Check all four levels in order.
Authors run the same triggers before they push. Assume they did. Treat what you find as missed, not as dismissed.
The correctness pass
You owe every PR a correctness pass, and you run it yourself. Read the diff for the defects a reviewer is here to catch: a nil or error path that returns the wrong value, a boundary the change moved, a resource that leaks on the failure branch, concurrent access the diff introduced, and a call whose behaviour the diff changed without changing its callers.
Then run the triggers above that fire for this diff, plus the compliance hierarchy. Together they are the whole review. There is no second reviewer to defer to and no plugin to invoke, on a developer's machine or in the review workflow.
The same skill runs on a developer's machine and in the review workflow. A PR gets the same treatment either way.
What blocks a merge here
The severity split matters more than any single finding. It decides what the author must act on. Reserve the blocking tier for four things.
A violation of CONSTITUTION.md or DESIGN.md. Two cases recur. The agent
output contract: a command declared finite in
cmd/gcx/root/testdata/output_classes.json must write exactly one JSON value to
stdout. A flag that writes a file and leaves stdout empty breaks that contract.
Stream routing: a status line or a fallback notice on stdout lands inside a
user's redirected output.
A regression to a released command surface. A removed or narrowed flag value,
a changed exit code, or a changed output shape that existing --json or --jq
callers depend on. The surface is stable within a major version.
Behaviour that changes inside a diff the author describes as a refactor.
A credential that escapes. An error message that quotes a token, an authorization code, or a password. A prompt that leaves one in the terminal input queue when the flow exits early, where the shell then reads it. Where a diff adds a control for this, check that it runs on every exit path and not only on success.
Report findings about naming, structure, duplication, and test shape as nits. Do that even when the argument for them is strong.
Do not report
- Anything CI already enforces:
mise run lint, the test suite, theDocumentationbuild,validate-skills, and the conformance suites incmd/gcx/root/. - The generated release snapshot
docs/sources/cli-reference.md, and anything invendor/. - Missing test coverage in files the diff did not touch.
Report shape
Use bold text for headings in the report, not markdown headings. Each section should be at most two sentences.
- Intent. The problem, and how the change solves it. Say whether the approach is sound before you list what is wrong with it. Do not give an opinion non whether the approach is sound or not here - that will become obvious from the rest. Keep this as short as possible.
- Blocking. Fix before merge: correctness bugs, regressions to shipped behaviour, safety defects, and violations of CONSTITUTION.md or DESIGN.md. Also: Behaviour that changes inside a described refactor. A call to a function, field, or option that does not exist. Overengineering issues from T12 and T5. If nothing blocks the merge, omit this section.
- Other findings. Everything that does not block, worst first. Include documentation that contradicts the code it describes. Give each finding the space its argument needs and no more. Some take a paragraph. Most take a line. The label shows the difference, so a one-line nit and a worth-fixing defect can share the list.
- Fix summary One combined remedy. Omit this section when section 2 and 3 are empty.
- Verdict. Approve or request changes. Name the findings that decide it. If you would merge a reduced version, say so, and say how much smaller.
Rules that keep the report honest
One finding per code unit, not per check. Name the symbol, file, or flag. Two findings that name the same symbol are one finding. Combine them and list every check the unit trips. State the count as evidence. Never split one unit across sections. A split unit turns one problem into five complaints about the same file.
Rank section 4 by lock-in. Lock-in is what the thing costs to remove after release:
- Exported API with fewer than two callers
- User-visible surface: flags, output shape, command paths
- Internal structure: duplicate types, thin wrappers, copied code
- Tests and unreachable branches
Break ties by line count. Cap the section at six findings. Move the lowest-ranked ones to section 3 as one-line nits. The ranking is mechanical on purpose, so two reviewers produce the same order.
Give one remedy, not one per finding. Section 5 is an ordered list of deletions and merges. Together they resolve everything in section 4. State the resulting size change against the real diff size. The size is evidence for the whole set. It is not a finding, and it does not belong in section 4.
Say what would overturn each blocking finding. This makes you look for the author's reasoning before you write. It also gives the author something specific to answer instead of a verdict to argue with. A comment at the call site does not settle the question. Reviewing as though that comment is absent wastes a review round.
A large diff is not always an unjustified one. A three-command feature with generated reference docs and real client tests is legitimately large. Say so. Judge the diff against its problem, not against a line count.
Order the blocking findings by severity too. A regression to shipped behaviour outranks a violation a maintainer can waive in the PR. Say which is which. Otherwise five blocking findings look heavier than the change deserves.
When a workflow invoked this
Six things change when no human is present. The rest of the review is the same.
- Deliver without asking. The offer below applies when a human can answer. In CI nobody can, and the trigger is the consent. Deliver through Workflow delivery below. You do not publish anything yourself.
- Never approve or request changes. Post whatever you found as a comment. Whether a finding is cheap enough to merge over is a judgement about the author's time. An unattended run cannot make it.
- Drop what you could not establish. Do not label it unverified. No author can answer a speculative finding here, and a wrong one makes them disprove it in public.
- Use tighter caps: at most three blocking findings, and eight comments in total. Drop the lowest-ranked findings.
Close the summary with this exact line:
Comment
@claude reviewfor a fresh review.- Upgrade
recommendedfindings to blocking. A human reviewer can weigh a should-fix in conversation. Nobody is here to do that, so a finding is either worth the author's attention or it is a nit.
Silence is a valid result. If there are no findings, say so in one line and deliver that line. Never invent a finding.
Silence is not the same as a pass you did not run. If your correctness pass could not complete, say that instead. Never deliver "no findings" for a review that did not happen.
If the prompt lists a previous review commit and findings, use them as context: run git diff <previous review commit>..HEAD to check whether each earlier finding was actually addressed, do not post a previous finding again as a new comment, and say in the summary which earlier findings are addressed and which still stand.
Workflow delivery
Return the review as this run's structured output:
{"review": {"body": "<the summary>", "comments": []}}body is the summary. comments carries the inline findings, mapped exactly as
in Mechanics below: path, line, side and body on each one, plus
start_line and start_side for a range. A complete review that found nothing
keeps its one-line summary and an empty comments array. If your correctness
pass could not complete, return {"review": null}; that is not a clean review,
and the workflow fails the run instead of publishing one.
Anchor every line against the PR head, not the tree you are standing in. A workflow run checks out the merge ref, and its line numbers can differ from the head's. Mechanics below has the commands for checking.
Publish nothing in this mode — not through gh, not through an
inline-comment tool, not as a PR comment. The workflow submits the payload as
one COMMENT review against the commit it gave you, appends its own run marker,
and checks GitHub's response before the job goes green. There is no label to
set and no marker for you to carry.
Offering to post the review
After the report, offer to post it to the PR as inline comments. Do not post without an explicit yes. The comments are public, they carry the invoker's name, they land on someone else's PR, and you cannot undo them quietly.
Present the event choice with a recommendation and the reason for it:
| Report state | Recommend |
| Section 2 empty, section 3 empty | APPROVE |
| Section 2 empty, section 3 has findings | APPROVE with the comments attached |
| Section 2 has findings, all cheap to fix, none a regression to shipped behaviour | COMMENT |
| Section 2 has a regression, a safety defect, or anything expensive | REQUEST_CHANGES |
State the recommendation, then let the invoker choose. The report's verdict judges the code. The event judges a colleague's work, and that choice is theirs.
Mechanics
One POST creates the whole review, both the summary body and every inline
comment. The author then gets one notification instead of ten. Pass the JSON
directly on stdin; the tracked allowlist grants no file-write permission. A
quoted heredoc keeps backticks, dollar signs, and suggestions literal:
gh api repos/grafana/gcx/pulls/{n}/reviews -X POST --input - <<'REVIEW_JSON'
{
"event": "COMMENT",
"commit_id": "<reviewed head SHA>",
"body": "<the summary>",
"comments": []
}
REVIEW_JSONReplace the placeholders, use the chosen event for a human-invoked review,
and put the inline findings in comments. Leave it empty for a clean review.
Keep the endpoint first, unquoted, and followed by -X POST, matching the review
permission in .claude/settings.json. Record the returned review ID. If
publication is denied, stop and report the failed command. Do not retry through
scripts, post test comments, or switch to a regular PR comment.
Each comment needs path, line, and side. Use RIGHT for the file after
the change. A range also needs start_line and start_side.
Check every line number against the PR head. Diff line numbers are different, and a wrong anchor puts the comment on unrelated code:
git fetch origin pull/{n}/head:refs/pr/{n}
git show "refs/pr/{n}:path/to/file.go" | grep -n "<the code you are commenting on>"The line must fall inside a diff hunk. Context lines inside a hunk are valid.
GitHub rejects lines outside every hunk. A suggestion block replaces exactly
the lines you anchor it to, so match the indentation of the target. Go files use
tabs.
Report sections split like this. Sections 2, 3, and 4 become inline comments at the symbol each one names. Sections 1, 5, and 6 have no line to attach to, so they become the summary body.
Rewrite the findings as comments
Never paste report prose into a thread. A finding that fills four paragraphs in a document is too long to read in a review thread.
- Write two to four sentences. Start with the mechanism. End with the ask.
- Turn "what would overturn this" into a question the author can answer.
- Start with a bold label that says what the author must do. The summary names only the blocking findings. Without a label, the author has to work out which of the other comments they must act on.
- Use a
suggestionblock for any concrete one-line change. - State conclusions, not process. "The extraction preserves every check in both
paths: state → … → all 8
Resultfields" helps the author. "I checked this line by line" describes you instead. - Do not open with a compliment. Where the work deserves praise, one specific line at the end says more.
When one finding covers several sites, anchor it at one site and name the others
in the text (also flow.go:160, gcom.go:145). Ten comments make a review.
Thirty make noise.
Labels
The label follows from the section. That makes it mechanical instead of a second judgement:
| Section | Label | Means |
| 2 Blocking | **required** | fix before merge |
| 3 Other findings | **recommended** | should fix, does not block the merge |
| 3 Other findings | **nit** | take it or leave it |
| 4 Over-engineering | **followup** | fine to defer to its own PR |
Written out:
required — this returns on every
readLineerror, not just theCloseone the comment describes. …
Two adjustments. Label a section 4 finding **nit** when it is small enough to
fix in the same sitting. Where the author may ignore a **nit**, say so in the
text as well as the label.
Say what the labels mean once, in the summary body, with the counts. The author wants the shape of the review before the detail:
comments below are prefixed required (2), recommended (4), followup (2), nit (2)
Only label a comment **required** when it sits in section 2 of the report. One
inflated label teaches the author to ignore every label in every later review.
Language
Write the report and the comments in plain English:
- Short sentences. One idea in each.
- Active voice.
- Plain words instead of figurative ones.
- No idiom.
- Avoid phrases or terms that hyphenate words together. Find simpler alternatives.
This applies to prose. It does not apply to identifiers, code comments, suggested diffs, or quoted output.
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.

