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.
3. 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.