Runbook: Run a Review or Scan

docs / process / runbooks / run-a-review-or-scan

← all docs

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 scan send 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

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

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.