| name | claude-review |
| model | opus |
| description | Judge a working diff or pull request against this repo's CI review contract (.github/claude-review-prompt.md) — the same judgment the "Claude review" GitHub Actions workflow applies. Classifies findings; never edits files. |
Claude review (local)
Mirror the "Claude review" GitHub Actions workflow's judgment (BE-0203) on demand, against any
diff — a pre-push working diff, or an already-open pull request — so the same contract audits a
change before it ever reaches CI, or again on a live PR beyond what @claude review's own trigger
rules cover (BE-0347). This skill only judges; it never edits a file. Whatever invokes it — a
human, or another skill's own self-review step — decides what to do with its findings: apply them,
escalate them, or note them as a deliberate trade-off.
This packages the same judge-only review/plan pass ideation step 5
describes inline as its canonical procedure — the two restate the same cap, taxonomy, and dedup
rule independently, so keep them in sync if either changes.
When to use this directly
Invoke it yourself when you want the CI reviewer's exact read on a change without waiting for a push
and a bot round-trip: mid-session, on a working diff nobody has committed yet, or against an open PR
when you want a fresh contract pass right now rather than posting @claude review and waiting.
Inputs
- The diff. Either:
- a working diff — uncommitted or unpushed local changes. Stage anything untracked first
(
git add -N <paths> — an untracked file is invisible to a bare git diff, and -N records
the path without staging its content, so this judge-only pass never changes what a later commit
would pick up), then diff against the
branch point: git diff $(git merge-base HEAD origin/main) -- <paths>. Scope <paths> to
whatever's actually in play — the whole tree by default, narrower when the caller's own remit is
narrower.
- a pull request —
gh pr diff <PR> for the full current diff.
- Whether a live PR exists. A pull request carries discussion and a history of findings this
pass must not repeat; a pre-push working diff carries neither.
Steps
1. Read the contract
Read .github/claude-review-prompt.md in full — the same
file the CI job reads. It is the source of truth for every rule below: the severity floor (functional
impact only — no nitpicks, no praise), the prime-directive lenses, the design/security/semantic/test
lenses, and the two prose-quality lenses with their own stricter floor. Read it fresh each time
rather than from memory, since it changes independently of this skill.
2. Read the existing discussion (live PR only)
Skip this step for a pre-push working diff — there is no discussion yet.
For a live PR, read gh pr view <PR> --comments for the conversation, and the inline review
comments already posted (gh api --paginate repos/{owner}/{repo}/pulls/<PR>/comments) so you know
what is already on the thread — --paginate matters once a PR has accumulated more than a page of
prior comments. Hold yourself to the contract's own dedup rule: never restate a point a
human, GitHub's native reviewer, or an earlier pass already made; treat a thread a human already
resolved as settled; and still raise a genuinely new problem anywhere in the diff, even on code an
earlier pass overlooked — dedupe by suppressing repeats, never by narrowing what you read.
3. Review cold, against the whole diff, in one pass
Apply every lens in the contract to the entire diff named in the Inputs section above — the prime directives,
design/architecture, security, the silent-failures/type-design/test-coverage lenses, the semantic
bug classes, test quality, and the two prose lenses. The prose lenses' own scope is the contract's,
not a path filter: the Japanese lens covers any Japanese the diff adds or edits, including Japanese
in a code comment, and the English lens covers docs/*.md and roadmap BE-NNNN-<slug>.md prose.
Only the (non-blocking, prose) marker in step 5 is restricted to docs/ and roadmaps/ files.
Read every changed file in full before finishing; a shallow first pass that leaves the rest for
"next time" is the dribble the contract explicitly forbids, and there may be no next time.
When another skill's self-review step spawns this pass, it runs as a fresh Agent-tool subagent with
no memory of the calling conversation, and the caller may override the model for that call (for
example pr-followup runs it on fable). Give that subagent only the contract text and the
diff — not the calling skill's authoring conversation. The CI reviewer runs cold, with no memory of
why a line was written; a subagent that inherited that context would not reproduce its judgment.
4. Classify every finding that clears the severity floor
This pass never edits a file — it classifies. Every finding that clears the contract's severity
floor comes back as one of:
- a fix instruction — the file, the exact location, and the exact change to make;
- an escalation — a finding that calls for a genuine design change, which is the caller's (or the
user's) call, never this pass's own;
- noted and left as-is — a false positive, or a deliberate trade-off the diff or its PR
description already explains, recorded with its rationale so a later round doesn't re-raise it.
5. Report or post, depending on the target
- Working diff, no live PR: return the classified findings as structured text to whoever
invoked this skill (another skill's implement pass, or the user directly). Nothing gets posted
anywhere.
- Live PR: post inline comments with
gh api directly — an interactive session has no
mcp__github_inline_comment tool, which exists only inside the claude-code-action environment the
CI workflow runs in. Post every new fix instruction, escalation, and question as an inline PR
review comment — never a top-level summary (a fresh summary on every run leaves stale,
contradictory overviews across a PR's several passes). Follow the contract's exact format: prefix
every comment 🤖 **Claude Code** — , then a Conventional Comments label
(issue / suggestion / question) and the (non-blocking) decoration — (non-blocking, prose)
instead, on the two prose lenses' findings, and only in a docs/ or roadmaps/ file — and attach
a GitHub suggestion block wherever the fix is mechanical enough to express as replacement lines.
Post via gh api repos/{owner}/{repo}/pulls/<PR>/comments with -f path=…, -F line=…,
-f side=RIGHT, -f commit_id=…, -f body=… — line goes through -F, which serializes it as
a JSON number; -f would send "42" and the endpoint rejects the call with a 422. Fetch
commit_id from the PR's current head first
(gh api repos/{owner}/{repo}/pulls/<PR> --jq .head.sha), since a stale or unrelated SHA gets
rejected or anchors the comment to the wrong diff context. When nothing clears the floor, post
nothing — silence is a complete review.
Looping until clean (no live PR)
When there is no PR yet, re-run this whole procedure against the updated diff after your own
implement pass applies its fix instructions, carrying forward this round's noted-and-left-as-is
findings (with their rationale) into the next round's input, since each round is spawned cold with
no memory of earlier dispositions and would otherwise re-flag them forever. Stop when a pass returns
nothing (an empty pass is a complete review, per the contract's own closing rule) or once you've run
3 review/plan passes, whichever comes first — an LLM-based reviewer is not fully deterministic and
could keep surfacing a fresh marginal finding every round, possibly one its own previous fix just
introduced. On the 3rd round still returning a real finding, stop and let the user decide rather
than looping further. The cap counts review/plan passes (this skill's own invocations), not fix
attempts.
What this skill does NOT do
- Edit any file. Applying a fix instruction is the caller's job (its own implement pass), never
this one's.
- Decide whether a PR merges. This is advisory review only (prime directive 1) — the deterministic
check / E2E gates are the only merge arbiters.
- Post a top-level summary comment on a live PR.
- Re-post a finding already on a PR's thread, or reopen a thread a human already resolved.
