continuum-ai-corp/orca-code-review/orca-review

OrcaCode Review — local review

You are the reviewer. Your own model does the thinking; the CLI does everything that must not be left to a model — which files are in scope, which rules apply, whether a finding is filed on the right line, and what blocks a merge.

This is the same severity contract the GitHub Action enforces, so a P1 you find here is a P1 that would block there. That parity is the point: "it passed locally" has to mean something.

Severity contract: P0 critical / P1 high → ❌ block. P2 conditional bug / P3 nit → 💬 report, never block.

When this skill applies

Nothing here talks to OrcaRouter. If the user wants automatic review on every PR, that is the other skill.

Workflow

1. Plan

npx @orcarouter/code-review review plan --lang en   # en | zh | ja | ko

--lang is the language the user is speaking to you in — en, zh, ja, or ko. Do not copy the example's value; read the conversation. An English request gets en, a Chinese one zh. Pass it on every command. The plan will tell you to write your findings in that language, and submit will render its report in it. Without the flag the CLI falls back to the machine's locale, which is usually right and sometimes is not; you know which language the conversation is in, so say so.

Everything you say to the user is in that language too — the one-line acknowledgement before you start, the report you relay, the next step you offer, the settings question. A Chinese request answered with "I'll review PR 92" and then a Chinese report reads as two different people.

It prints a complete review request to stdout: the files in scope, the files it excluded and why, the git command that shows each change, per-language review checklists, the full P0-P3 rubric, the project's own conventions, and the exact result shape. Progress notes go to stderr, so the stdout text is the whole prompt and nothing else.

Read all of it. Everything you need is in there — do not go looking for a rubric elsewhere, and do not substitute a severity scheme you know from somewhere else.

The file list has already been filtered: binaries, deleted files, unsupported types, tests and fixtures and generated code, and anything under .gitignore are listed under Excluded with the reason. Do not review those, and do not second-guess the list — it is the same selection CI applies.

2. Review

Work file by file through the list in the request:

1. Get the diff with the command the request gives you.
2. Read the actual file, not just the diff. A finding you cannot confirm by

reading the surrounding code is a finding to drop.

1. Apply that file's rule group, then the severity rubric.

Comment only on changed lines. The rubric's precision section is binding, in particular: one comment per distinct issue, never the same root cause restated per file, and never a finding pinned to a file you did not open.

3. Hand back

Write .orcacode-review/result.json in exactly the shape the request specifies. Four fields per finding, and nothing else — the file is an internal handoff, not a report, and every extra byte is a line of raw JSON scrolling past the person watching you work:

{"comments": [
  {"path": "src/auth.ts", "line": 41,
   "existing_code": "  if (token === expected) {",
   "content": "[P0] **Title**\n\nBody."}
]}

• path — repo-relative, and it must be the file that actually contains the code.
• line — in the post-change file. Only for a finding that genuinely spans

several lines, write start_line/end_line instead.

• existing_code — the source you are quoting, copied verbatim. This gets

grepped against the tree to check you filed the finding on the right file. A paraphrase here reads as a wrong location and the finding may be dropped. One line is enough; do not paste a whole function.

• content — [P0]/[P1]/[P2]/[P3], then a bold title, then the body,

written in the user's language. The tag, the bold, and the separate Fix: paragraph are structure and never change; the words inside them do. Identifiers, paths, and code stay verbatim.

Found nothing? Write {"comments": []}. That is a clean review, not a failure.

warnings is optional and you will almost never want it: it lists files you could not review, and a non-empty warnings makes the review partial, which submit rejects rather than passes. Omit the key unless something genuinely failed.

4. Submit

npx @orcarouter/code-review review submit --format md --lang en   # same --lang as the plan

Same --lang as the plan, so the report's verdict line and headings come out in the user's language alongside the findings you wrote in it.

This verifies every finding's position against the tree, drops duplicates, tags what would block a merge, and prints the report as markdown.

Use --format md rather than the default. The default is an ANSI terminal report hard-wrapped at 78 columns, which arrives in a conversation as a wall of pre-formatted text.

Relay that markdown to the user verbatim. It is written to be read in a chat: grouped by file, blocking file first, ❌ on what stops the merge and 💬 on what does not. Do not re-summarise it, do not re-order it, and do not substitute your own severity call — the gate decides what blocks, not you, and it will have re-homed or dropped findings you were about to report.

The exit code is not the verdict. submit exits 0 whenever the review ran, blocked or not — your job is to tell the user what the bugs are, and that is the report. The line under its heading says which it was: ❌ (Blocked, 已拦截, …) means something at P0/P1 would stop a merge, ✅ means nothing would. Relay whichever you got.

Exit 2 is the only failure, and it is never a pass. (A 1 only exists under --fail-on-block, which is for hooks and CI scripts — you have no reason to pass it.)

The same markdown is always saved to .orcacode-review/report.md.

Then say, in one line, what you would do next. Offer to fix; do not start fixing unless the user asked for it in the first place.

The first review in a repository

If the plan ends with a section titled First review in this repository, there is no .orcacode-review.json yet. Do the review exactly as normal. Then, after the report is on screen, offer once — one sentence — to save the settings this run used, and say what saving buys them: the next review here needs no flags, for them or for anyone else who clones the repo. Something like:

这个仓库还没有本地评审配置。要我把这次的设置（中文、P0/P1 阻塞）存成

.orcacode-review.json 吗？以后在这里评审就不用再指定了。

Yes → run the review config init command the plan gives you, apply anything they asked for on top, show them the file. No → drop it for the rest of the conversation. Never create the file without being asked, and never ask before the report: they should decide with the output in front of them, not in the abstract.

Changing how the local review behaves

The repo's local review settings live in one committed file, .orcacode-review.json. When the user asks for a lasting change — not "this once" but "from now on" — edit that file; do not reach for a flag, and do not put it in CLAUDE.md.

Before editing, run this to see what applies now and where each value came from:

npx @orcarouter/code-review review config --lang en   # the user's language

If the file does not exist yet, create it with the template rather than by hand:

npx @orcarouter/code-review review config init --lang en   # the user's language

Then edit only the key the user asked about. Show them the resulting file. Keys you do not write keep their defaults; unknown keys are an error, not a typo the tool overlooks — if plan or submit refuses with ".orcacode-review.json is invalid", read the message, it names the key and the allowed values.

The four keys, and nothing else:

• block_on — "P0,P1" (default), "P0", or "". What the report marks ❌.
• language — en | zh | ja | ko. Outranks the machine locale; --lang

still outranks it.

• exclude — extra globs never to review, on top of the bundled rules.

docs/**, **/*.snap, legacy/**.

• rules — extra checklists. Each { "path": glob, "rule": "text" } or

{ "path": glob, "rule_file": "docs/review/api.md" }. By default the text is added to the bundled checklist for those files; "replace": true swaps it in instead.

For a one-off ("just this time only block on P0") use the flag on that one command instead, and change nothing on disk.

Choosing the range

With no flags it picks for you and says which it picked: uncommitted work if the tree is dirty, otherwise this branch against its base — the range CI would use. Override when the user was specific:

Pass --background "…" when the user has told you what the change is for. It goes to the reviewer — you — as business context, and it is what lets you judge whether the change does what it was supposed to. With --pr the PR's title and description become the background automatically; only pass --background on top of it if the user told you something the PR does not say.

Reviewing a pull request by number

--pr needs the GitHub CLI (gh) and does not check the branch out. It fetches the PR into a private ref and leaves the work tree exactly as it was — so it is safe to run mid-change, and you must not git checkout or git stash around it. Fork PRs work; the head is fetched from the base repository.

If it reports that gh is missing or not signed in, do not try to install or authenticate it. Say so, and offer the fallback the CLI prints:

gh pr checkout 556     # the user runs this, then you review with no --pr

Getting it wrong