PR Review
One question — what do I do about this pull request — answered differently depending on which side
of it you are on.
Their branch. You are the reviewer. Attack the diff, then publish a real review: one inline
comment per finding, a body, and a verdict.
Your branch. You are the author. Work the threads people and bots left: decide whether answering
is even your business, check whether the claim is true, then reply and close what is finished.
The skill verifies before it speaks and changes no code unless asked. Its default output is
an action report plus whatever it posted.
The premise
Bots write most of the inline comments on a modern pull request, and they fail in a shape: the
premise is wrong far more often than the conclusion. The claim rests on how a framework behaves,
and your repository's own code says nothing about it — so "read the code" is not enough, and two
agents agreeing is not verification.
The ordering is therefore fixed and not negotiable:
verify → fix → build → speak.
Never post a verdict you have not executed. A
needs evidence that can be pasted; a
needs the project's own checks passing on it.
references/verifying-a-claim.md
has the traps, the
version-pinning discipline, and the run where a fabricated claim reached two independent
confirmations and was caught only because the fix would not compile.
Configuration
| Setting | Flag | Default |
|---|
| Apply code changes | | Off — verify, check, report |
| Verification breadth | | Bot claims, plus anything heading for or |
| Unattended | | Off — previews and confirmations are shown |
Explicit instructions in the invocation override the default posture in both directions. "Just
triage this" stays read-only however the postures resolve; "answer Anna" acts on a human thread that
the table below would have left alone.
is meaningless in reviewer mode — you do not fix a colleague's branch. Say so and ignore it.
Asking the User
Every question in this skill is written as
options. Use that tool where
the host offers it, or the host's nearest structured-choice equivalent. Where the host has
neither, ask the same question in normal chat as a numbered list of 2–5 options —
recommended first, one short line of description each — and wait for the user to reply
with a number.
Phase 1: Resolve the target and your side
Parse the invocation:
| Input | Meaning |
|---|
| empty | The current branch's open pull request |
| a number or a PR URL | That pull request |
| a URL | That single thread, and nothing else |
| a login () | Only threads that author rooted |
| free text | Threads whose body fuzzy-matches it |
Then resolve which side you are on, because it selects the mode:
bash
gh pr view <N> --json author,headRefName,baseRefName --jq .author.login
gh api user --jq .login
Equal → author mode. Different → reviewer mode. Announce which:
Reviewer mode on PR #534 by ashklianko.
If no pull request resolves, say so and stop.
Phase 2: Fetch
One query, up front, per
. It carries the thread and comment ids that
replying and resolving need, the
that decides bot from human, and
for
outdated threads. Read that file before writing the query — the previous version of this skill could
not reply or resolve at all, because it fetched neither id.
Do not filter resolved threads out of the fetch. Filter in Phase 3.
Phase 3: Standing
Resolved before any verdict, because it decides whether a verdict is yours to state at all. A
single-bot thread on your own pull request and a two-human argument you were never part of are not
the same situation and must not be treated alike.
| Your side | Thread rooted by | Last comment by | Posture |
|---|
| Reviewer | — | — | Author the review. Phase 7 publishes it |
| Author | Bot | bot only | Act — verify, reply, resolve. Code only under |
| Author | Bot | you | Already answered. Hands off |
| Author | Bot | another human | May add a technical fact. Do not resolve |
| Author | Human | that human | Draft a reply, confirm before posting. Never resolve |
| Author | Human | you | The ball is in their court. Do nothing |
| Author | 2+ other humans, you unmentioned | — | Read-only. Report as context, never reply |
A bot's own follow-up does not count as a human reply. Only a
moves the last-comment axis.
Resolved threads are out of scope unless
or an explicit instruction brings them back.
Phase 4: Verify
Per
references/verifying-a-claim.md
. Decompose each claim into its
premise about the world and
its
conclusion about this code, and verify them separately — recording which failed, because the
answer differs completely.
Pin the resolved dependency version before reading any artifact. Never a package located by
in
a global cache, never memory. Never apply a
block unread.
Scope: every bot claim and anything heading for
or
.
adds everything
unresolved, human claims included. Loose recommendations and other reviewers' summaries are reported
as context and never verified.
Phase 5: Verdict
Six, replacing the old
/
pair:
| Verdict | When |
|---|
| Real, and the change is yours to make |
| The premise or the conclusion is false. The reply carries the evidence |
| Handled elsewhere. is the hint |
| Correct, but the call belongs to a person — scope, architecture, product |
| Real, and deliberately not now |
| Praise or an FYI. Nothing to answer |
triggers on
authority, not difficulty. A hard fix you are confident about is a
.
Phase 6: Fix ( only)
Without
nothing is edited; a
verdict is reported and its thread left for a later run.
With it: one thread's finding at a time, then the project's own checks — whatever
,
or CI actually runs. A fix whose checks fail is reverted, not worked around, and its
verdict drops to
with the failure quoted. Never claim a fix that has not gone green.
Phase 7: Speak
Composition is in
: the answer in the first clause, real symbols rather than
descriptions, a link where one exists, ready concessions, and the decision handed back. A fix reply is
shorter — what changed, why, and the check that passed.
Reviewer mode publishes instead of replying. Invoke
to attack the diff and
verify what it finds, passing the pull request's own issue as the requirement and any system facts you
have, then let its publication phase post the review with
. It owns the inline anchoring,
the grouping of minors, and the verdict mapping; do not rebuild them here. Where the host cannot
invoke another skill, run the same attack inline and publish by the rules
documents
for it — one inline comment per finding, minors grouped, nothing published without a demonstration
and an attribution, and the verdict set by whether a blocker survived.
Confirm before anything leaves. In author mode show the composed replies; in reviewer mode show
the whole review — every inline comment, the body, the verdict — laid out locally first. Ask per
Asking the User — post as
written (recommended) / edit first / discard.
skips this and posts directly.
Resolve only what
permits: never a human-rooted thread, never a
.
Check
before attempting.
Output
## PR #<N> <author|reviewer> mode: <N> threads · <F> fixed · <R> rejected · <D> discuss · <X> deferred
<per thread: the claim in a clause, the verdict, and what was done>
Posted: <N replies, N resolves, or the review and its verdict>
Held: <what awaits your confirmation, or what --fix would have changed>
Context: <read-only threads, unverified chatter>
Deferrals are always listed even though their threads are closed. A deferral nobody can see is
backlog that does not exist yet.
Rules
- Verify, then speak. No verdict that was not executed. No fix claimed without a green check.
- Standing before verdict. Whether you may answer is decided before what the answer is.
- Never resolve a human's thread. Closing someone's thread is theirs to do.
- Premise and conclusion are separate claims. A bot's conclusion can be right for a wrong reason.
- The pull request belongs to its author. Suggest, do not instruct.
- No code without . Reporting a needed change is not the same as making it.
Error handling
| Situation | Action |
|---|
| No pull request resolves | Say so and stop. Do not review the working tree instead |
| Every thread is resolved | Say the pull request is clear. Do not manufacture findings |
| A claim cannot be verified either way | , with what you tried and what was inconclusive |
| The resolved dependency version cannot be established | Say so in the reply and make no version claim |
| is false | Reply where possible, resolve nothing, say why |
| A reply posts but the resolve fails | Say which thread is half-answered. Do not repost the reply |
| and the checks were already failing | Establish the baseline first; never blame a pre-existing failure on the fix |
| Host cannot invoke another skill | Run the review inline, per Phase 7 |
| in reviewer mode | Ignore it and say why |
| The project's check command is outside the pre-approved set | It will prompt for approval. Run it anyway — an unrun check is not a green check |