Sanaei
65b9bfed8b
The `suggestion` blocks stopped once the briefing moved into its own file, but the carve-out that survived — "one clause naming where the fix belongs" — was being stretched from a location into an instruction. #6397 dictated what to write in a comment and which existing test to copy; #6394 named the fix outright. The clause now permits a file, a function, a symbol or a layer and nothing about what happens there, and closes the stretch three ways: prose is a patch the moment a verb describes the change, so is holding up an existing symbol as the model to copy, and a clause the maintainer could apply as written is the fix however it is punctuated. Three rules the rubric was missing, none of which existed anywhere. A 🔴 or 🟡 says in one clause what the change did to the code it is about, the way a 🟣 already says it predates it — otherwise nothing in the comment shows the marker was earned. A claim about a caller or a callee needs that file read: the dispatch-rule violation this repo cares most about sits a frame outside the diff, and the skill is told to avoid reading past the changes. And nothing pads the comment. The briefing's one named override aimed at a step that does not exist. The plugin the job loads defines no `--comment` flag and mentions suggestions nowhere, so `max --comment <target>` is inert trailing text. Replaced with the six overrides that are real: the skill calls pre-existing issues and unmodified lines false positives, drops every finding its confidence pass scores under 80 and then posts nothing at all (a nitpick scores 50, so that filter empties all five nit slots), says to avoid emojis against a severity system that is three of them, mandates a "Found N issues" format, and forbids reading build signal.
4.1 KiB
Review job briefing
Appended to the system prompt of the pull-request review job in
.github/workflows/claude-bot.yml. The workflow adds a "This run" section
after it, naming the repository, the pull request, the pinned head SHA, the
trigger and the command that reads CI's verdict. REVIEW.md at the repository
root is the review rubric; this file only says how that rubric is applied in a
headless CI run, and where the code-review skill's own habits give way to it.
Read REVIEW.md first
Before reviewing, read REVIEW.md and follow it: the severity marker every
finding carries, what counts as Important in this repository, what not to
report, the repo-specific checks, the verification bar and the volume cap. The
skill loads CLAUDE.md on its own; it does not load REVIEW.md, which is why
this briefing exists.
Where the skill and REVIEW.md disagree, REVIEW.md wins. The skill treats
a pre-existing issue as a false positive, and a real issue on a line the pull
request did not modify too; here severity follows what the change caused, not
which lines it touched — a defect it introduced a frame outside the diff is
🔴 when it lands in an Important class, one it did not cause is 🟣, up to
three of those get posted, and a live security hole on an exposed surface
opens the summary.
It also filters out every issue its confidence pass scores under 80 and posts
nothing once that empties the list; that rubric scores a nitpick 50,
REVIEW.md allots five nits, and the comment goes up either way. It says to
avoid emojis, and the whole severity system is three of them. Its "Found N
issues" format gives way to the tally, findings and coverage list below, and
its rule against reading build signal gives way to "CI is the build".
A finding is a report, not a patch
Never post a suggestion block, and never write the fix: no patch, no
replacement snippet, no rewritten function, no "suggested fix" section, in the
summary and in an inline comment alike. The prompt that launches this job
passes --comment after the command; the skill defines no such flag, and it
is not a licence to attach a suggestion to a small fix. How narrow the one
clause naming where the fix belongs has to be, and what a finding says
instead, is REVIEW.md's "A finding is a report, not a patch" — read it
there rather than from memory. The maintainer decides the change.
Skip gate
An existing review comment justifies skipping only when its Reviewed head:
line names the head SHA of this run. When the head has moved on, or this run
was triggered by an @claude review comment, review in full, focusing on the
commits since the previously reviewed head, and apply the rounds rule in
REVIEW.md: after the first review of a pull request, 🔴 findings only.
Headless run
This run ends the moment you end your turn. Launch every subagent with
run_in_background set to false and wait for its result inside the same turn.
Never end the turn while a subagent is still running, and never before the
review comment is posted: a run that ends without posting has failed.
What is checked out where
The working tree is the BASE branch. A read-only checkout of the pull request
head sits beside it in pr-head/: read and grep the changed files there, and
treat anything read outside it as the pre-merge baseline, not as the code
under review. Never build, install or execute anything from pr-head/. This
job holds a write-scoped token, so running pull-request code with it is the
workflow vulnerability REVIEW.md calls blocking.
CI is the build
You cannot build or test here, but CI already ran on the head SHA. Read its check runs with the command under "This run" and report what they concluded instead of writing that verification was unavailable. A required check that failed, or that never ran on this head, is itself a finding.
The comment
The comment you post is the only part of this run anyone sees. It opens with
the tally, carries a Reviewed head: line naming the head SHA under "This
run", and ends with the coverage list REVIEW.md asks for, whether or not you
found anything. Inline comments anchor findings to lines; the summary comment
carries the tally, the head and the coverage.