Runbook: Run a Review or Scan
Owner: Any developer / CI job | Frequency: Per change (review) or as needed (scan) Last Updated: 2026-08-14
⚠️
ocr review/ocr scansend diff or file content to your configured LLM provider over HTTPS. Only run against repositories you're authorized to send off-machine, and confirm Setup & Credentials is complete first.
Purpose
Run an AI code review against a git diff or whole files, and read/act on the results. This is the everyday operation for both a local developer and a CI pipeline.
Prerequisites
- [ ] OCR installed and an LLM provider configured (see Setup & Credentials).
- [ ] You're inside a git repository (for
review) or any directory (forscan).
Procedure
Step 1a: Review — workspace changes
cd your-project
ocr review
Expected result: OCR reviews all staged, unstaged, and untracked changes and prints
comments to the terminal, grouped by file.
If it fails: "No supported files changed" means every changed file was filtered by
rule.json or the built-in allowlist — see Troubleshooting below.
Step 1b: Review — a branch range or single commit
ocr review --from main --to feature-branch # merge-base mode
ocr review --commit abc123 # single commit vs its parent
Expected result: same output shape, scoped to the given range/commit.
If it fails: confirm both refs exist locally (git rev-parse <ref>); OCR diffs what
git can resolve, it doesn't fetch.
Step 1c: Full-file scan
ocr scan # whole repo
ocr scan --path internal/agent # a directory or specific files
Expected result: whole-file review comments — useful for auditing code with no
meaningful diff (e.g. a codebase you've just inherited).
If it fails: narrow --path — a whole-repo scan on a large codebase can hit
--max-tokens-budget before finishing; see Step 2 to resume rather than restart.
Step 2: Resume an interrupted run
ocr session list
ocr review --from main --to feature-branch --resume <session-id>
# or: ocr scan --resume <session-id>
Expected result: OCR reuses every file that already completed in the prior session (matched by content fingerprint — see LLD §8) and only re-reviews what didn't finish. If it fails: if the diff/scope changed since the interrupted run, the content fingerprint won't match and nothing will be reused — that's expected, not a bug.
Step 3: Inspect a past session
ocr session show <session-id>
ocr session comments <session-id>
ocr viewer # browse the same session history in a local web page
Expected result: the full task record (prompts, tool calls, responses) or just the
final comments, without re-running anything.
If it fails: ocr session list first to confirm the session ID is correct and still
present in local session storage.
Verification
- [ ] Exit code is
0for a fully completed review; non-zero (with output explaining why) for a run where nothing was reviewed successfully. - [ ]
[ocr] N file(s) changed, reviewing M in <repo>line at the start matches your expectation for the diff/scope you gave it.
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| "No supported files changed. Skipping review." | Every changed file was filtered by rule.json's include/exclude or the built-in file-type allowlist |
ocr rules check <file-path> to see exactly which rule/filter applied. |
| Review stops partway with a token-budget message | --max-tokens-budget was set and reached |
Expected behavior, not a failure — the manifest reports partial, not failed, if anything completed. Raise the budget or split the change. |
| Comments have a wrong-looking line number | Deterministic resolution failed and the model's re-location guess was wrong (rare) | Check ocr session show <id> for the re_location task record; this is the one case where a comment's location isn't guaranteed by parsing alone. |
Rollback
Review/scan never write to the repository under review in any mode — there is nothing
to roll back on the target repo. ocr session data lives entirely in OCR's own local
session directory and can be deleted independently.
Escalation
| Situation | Contact | Method |
|---|---|---|
| Review quality issue (false positive/negative pattern) | Team owning rule.json for the repo |
Adjust rules, or file feedback upstream |
| OCR bug | OCR maintainers | github.com/alibaba/open-code-review/issues |
History
| Date | Run By | Notes |
|---|---|---|
| 2026-08-14 | Onboarding kit build | Verified flags against cmd/opencodereview/{review_cmd,scan_cmd,session_cmd}.go and the project README's Quick Start. |