OCR Review-to-Approval Loop
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything.
Orchestrates an autonomous review → address → re-review loop on a pull
request, using Open Code Review's multi-agent review pipeline, until the review
reaches an APPROVE verdict, then runs one final address pass for leftover
suggestions. Every review and every address round is posted to the PR as a
comment, producing a transparent, reviewable audit trail.
OCR review → post review to PR → verdict?
├─ APPROVE → final OCR address (suggestions) → done
├─ NEEDS DISCUSSION → stop, ask the user
└─ REQUEST CHANGES → OCR address (fix + verify + commit + push)
→ post address comment → re-review
It is a thin orchestrator over two OCR steps it does not reimplement:
- Review: the 8-phase multi-agent review that emits a verdict.
- Address: corroborate a review's feedback against the code, then implement.
Configuration
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Code review (
docs/agents/workspace.md). Default: Open Code Review, with
reviewer teams in .ocr/config.yaml. Run OCR's review as the /ocr:review
command, or, in a harness without that command, by reading
.ocr/commands/review.md and following it. OCR's address step is the matching
/ocr:address, or .ocr/commands/address.md. If the configured system is not
OCR, this loop does not apply: tell the user and stop.
Check the dependencies first
The ocr CLI. Run command -v ocr and check .ocr/ exists in the
repository root. If either is missing, ask the user before installing, using
your structured-question tool if you have one; otherwise list numbered options
in plain text and stop until they reply. Offer:
- Load the
setup-aclarify-skills skill (through your skill tool,
/setup-aclarify-skills, or by reading its SKILL.md), which installs and
initialises the tools these skills use.
- Install directly:
npm i -g @open-code-review/cli, then ocr init in the
repository (pass --tools <your agent's id> to skip its prompt).
Run the commands only after the user agrees. If a command fails, print it for
the user to run. When setup looks off, ocr doctor diagnoses it.
The gh CLI, unless --no-post: gh auth status must pass. If gh is
missing, ask before installing it (brew install gh, or
https://cli.github.com); the user runs gh auth login themselves.
Arguments
ocr-review-loop [pr] [--team <spec>] [--max-rounds N] [--no-final-suggestions] [--no-post]
pr (optional): PR number. Default: the open PR for the current branch.
--team <spec> (optional): reviewer team override (reviewer-id:count,...),
forwarded to the review; it replaces the default team for this run.
Default: the project's default team (ocr team resolve). The catalog's
default, which setup-aclarify-skills writes, is one principal and one
architect, at most two reviewers.
--max-rounds N (optional): safety cap on review rounds. Default: 5. The
loop never runs forever.
--no-final-suggestions (optional): stop at APPROVE; skip the final
suggestions pass.
--no-post (optional): run locally; do not post to GitHub. Present the trail
in the conversation instead.
The loop
Execute this inline, to completion, in the conversation. Do not schedule across
turns or background the work. Drive each review's phases 4→7 within one turn
(OCR's "don't strand the pipeline" rule). Read references/loop-mechanics.md
for the exact CLI and session details and the PR comment templates.
0. Preconditions. Resolve the PR and branch; refuse to run on the default
branch. Confirm the dependencies above. Resolve the reviewer team (default unless
--team).
1. Review-address loop. Starting at round = 1, while the verdict is not
APPROVE and round <= max-rounds:
- Review: run OCR's review (default team, or
--team). It runs the full
pipeline and finalizes rounds/round-{round}/final.md and round-meta.json
with a verdict. From round 2, brief it as a re-review (see the guardrails).
- Post the review to the PR, headed
OCR review, round {round}. (skip if
--no-post)
- Gate on the verdict (read it from
round-meta.json, or final.md):
APPROVE: exit the loop (go to step 2 below).
NEEDS DISCUSSION: stop the loop. This is a human gate: surface the
clarifying questions to the user and await direction. Do not fabricate a
fix.
REQUEST CHANGES: continue.
- Address: run OCR's address step on
rounds/round-{round}/final.md.
Corroborate every item against the actual code; implement the blockers and
should-fixes (these clear the gate); decline incorrect feedback with
evidence; you MAY defer pure suggestions to the final pass. Verify with
the repository's checks until green, then commit (atomic, conventional) and
push.
- Post the address round to the PR: what was addressed, declined (with
reasoning), and deferred. (skip if
--no-post)
round += 1; loop.
2. Final suggestions pass (only after APPROVE, unless
--no-final-suggestions): run OCR's address step once more to clear remaining
suggestions, verify, commit, push, and post a final address comment that
includes a loop-summary table (round → verdict → outcome).
3. Stop conditions. If round exceeds max-rounds without APPROVE,
stop and report the outstanding blockers; never loop indefinitely. If APPROVE
was reached on round 1, skip the loop body and go straight to the final
suggestions pass.
Guardrails (critical, do not skip)
- Bounded. Honor
--max-rounds (default 5). If not approved by then, stop and
surface why.
NEEDS DISCUSSION is a human gate. Pause and ask; never invent a resolution
for genuine ambiguity.
- Corroborate, don't obey. Per OCR's address step: verify each finding against
the code; implement valid items; decline wrong feedback with evidence.
Don't gold-plate: fix only what the review actually raised.
- Prefer the structural fix that makes a defect unrepresentable over
correcting the instance. Correcting the instance is what feeds the next round a
new blocker.
- From round 2, brief the re-review as a re-review. Tell the reviewers that
the previous round's fix is the most likely source of this round's defect, and
require a claim-by-claim table (claim → TRUE/FALSE →
file:line) rather than a
fresh prose read.
- Never push red. Before every commit, run the repository's own checks: the
done-bar its agent instructions (
AGENTS.md or equivalent) or contributing
guide name, or else what its CI runs on a pull request (typically lint,
typecheck, test, build), scoped to the change where the tooling can scope it.
Fix failures before pushing. A passing check is not coverage: where a
finding is about what code or a document says, corroborate it by reading it,
not by re-running the checks.
- Never force-push. A shared PR keeps its history; corrections go on top.
- Branch safety. Refuse to run on the default branch; this skill commits and
pushes.
- Faithful reporting. Report verdicts and outcomes honestly. If a blocker
genuinely can't be fixed (it needs a product or architecture decision), stop
and say so rather than forcing APPROVE.
- New round, same session. Each iteration is a new OCR review round in the
same session (a closed session starts
round-{n+1}), reusing
discovered-standards.md and context.md.
Reference
references/loop-mechanics.md: per-round mechanics, verdict gating, session
and round handling, the re-review brief, and the PR comment templates.
1---2name: ocr-review-loop3description: >-4 Drive a pull request to an approved code review by looping Open Code Review's review5 and address steps until the verdict is APPROVE, posting every round to the PR as6 comments. Use when someone says review and address in a loop, iterate review until7 approved, auto review-and-fix this PR, loop the OCR review and address, or take a8 changeset all the way to a clean APPROVE. Needs a feature branch with an open GitHub PR.9 Do NOT use for a single review with no fixing (run OCR's review directly), or to10 address one existing review (run OCR's address directly).11license: MIT12argument-hint: '[pr] [--team <spec>] [--max-rounds N] [--no-final-suggestions] [--no-post]'13compatibility: Requires git, the Open Code Review CLI (ocr, Node.js 22.5 or later) initialised in the repository, and, unless --no-post, an authenticated gh CLI.14metadata:15 source: https://skillmd.com/skills/spencermarx/ocr-review-loop16---1718# OCR Review-to-Approval Loop1920Paths below are relative to this skill's directory; resolve them to absolute21paths before running anything.2223Orchestrates an autonomous **review → address → re-review** loop on a pull24request, using Open Code Review's multi-agent review pipeline, until the review25reaches an **APPROVE** verdict, then runs one final address pass for leftover26suggestions. Every review and every address round is posted to the PR as a27comment, producing a transparent, reviewable audit trail.2829```30OCR review → post review to PR → verdict?31 ├─ APPROVE → final OCR address (suggestions) → done32 ├─ NEEDS DISCUSSION → stop, ask the user33 └─ REQUEST CHANGES → OCR address (fix + verify + commit + push)34 → post address comment → re-review35```3637It is a thin **orchestrator** over two OCR steps it does not reimplement:3839- **Review**: the 8-phase multi-agent review that emits a verdict.40- **Address**: corroborate a review's feedback against the code, then implement.4142## Configuration4344This repository's agent configuration should have been provided to you (the45`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the46defaults below and suggest the user run the `setup-aclarify-skills` skill.4748- **Code review** (`docs/agents/workspace.md`). Default: Open Code Review, with49 reviewer teams in `.ocr/config.yaml`. Run OCR's review as the `/ocr:review`50 command, or, in a harness without that command, by reading51 `.ocr/commands/review.md` and following it. OCR's address step is the matching52 `/ocr:address`, or `.ocr/commands/address.md`. If the configured system is not53 OCR, this loop does not apply: tell the user and stop.5455## Check the dependencies first56571. **The `ocr` CLI.** Run `command -v ocr` and check `.ocr/` exists in the58 repository root. If either is missing, ask the user before installing, using59 your structured-question tool if you have one; otherwise list numbered options60 in plain text and stop until they reply. Offer:61 1. Load the `setup-aclarify-skills` skill (through your skill tool,62 `/setup-aclarify-skills`, or by reading its SKILL.md), which installs and63 initialises the tools these skills use.64 2. Install directly: `npm i -g @open-code-review/cli`, then `ocr init` in the65 repository (pass `--tools <your agent's id>` to skip its prompt).6667 Run the commands only after the user agrees. If a command fails, print it for68 the user to run. When setup looks off, `ocr doctor` diagnoses it.692. **The `gh` CLI**, unless `--no-post`: `gh auth status` must pass. If `gh` is70 missing, ask before installing it (`brew install gh`, or71 https://cli.github.com); the user runs `gh auth login` themselves.7273## Arguments7475```76ocr-review-loop [pr] [--team <spec>] [--max-rounds N] [--no-final-suggestions] [--no-post]77```7879- `pr` (optional): PR number. Default: the open PR for the current branch.80- `--team <spec>` (optional): reviewer team override (`reviewer-id:count,...`),81 forwarded to the review; it replaces the default team for this run.82 **Default: the project's default team** (`ocr team resolve`). The catalog's83 default, which `setup-aclarify-skills` writes, is one principal and one84 architect, at most two reviewers.85- `--max-rounds N` (optional): safety cap on review rounds. **Default: 5.** The86 loop never runs forever.87- `--no-final-suggestions` (optional): stop at APPROVE; skip the final88 suggestions pass.89- `--no-post` (optional): run locally; do not post to GitHub. Present the trail90 in the conversation instead.9192---9394## The loop9596> Execute this inline, to completion, in the conversation. Do not schedule across97> turns or background the work. Drive each review's phases 4→7 within one turn98> (OCR's "don't strand the pipeline" rule). Read `references/loop-mechanics.md`99> for the exact CLI and session details and the PR comment templates.100101**0. Preconditions.** Resolve the PR and branch; refuse to run on the default102branch. Confirm the dependencies above. Resolve the reviewer team (default unless103`--team`).104105**1. Review-address loop.** Starting at `round = 1`, while the verdict is not106`APPROVE` and `round <= max-rounds`:1071081. **Review**: run OCR's review (default team, or `--team`). It runs the full109 pipeline and finalizes `rounds/round-{round}/final.md` and `round-meta.json`110 with a `verdict`. From round 2, brief it as a re-review (see the guardrails).1112. **Post the review** to the PR, headed `OCR review, round {round}`. _(skip if112 `--no-post`)_1133. **Gate on the verdict** (read it from `round-meta.json`, or `final.md`):114 - **`APPROVE`**: exit the loop (go to step 2 below).115 - **`NEEDS DISCUSSION`**: **stop the loop.** This is a human gate: surface the116 clarifying questions to the user and await direction. Do **not** fabricate a117 fix.118 - **`REQUEST CHANGES`**: continue.1194. **Address**: run OCR's address step on `rounds/round-{round}/final.md`.120 Corroborate every item against the actual code; implement the **blockers and121 should-fixes** (these clear the gate); decline incorrect feedback with122 evidence; you MAY defer pure **suggestions** to the final pass. **Verify** with123 the repository's checks until green, then **commit** (atomic, conventional) and124 **push**.1255. **Post the address round** to the PR: what was addressed, declined (with126 reasoning), and deferred. _(skip if `--no-post`)_1276. `round += 1`; loop.128129**2. Final suggestions pass** (only after `APPROVE`, unless130`--no-final-suggestions`): run OCR's address step once more to clear remaining131**suggestions**, verify, commit, push, and post a final address comment that132includes a **loop-summary table** (round → verdict → outcome).133134**3. Stop conditions.** If `round` exceeds `max-rounds` without `APPROVE`,135**stop** and report the outstanding blockers; never loop indefinitely. If APPROVE136was reached on round 1, skip the loop body and go straight to the final137suggestions pass.138139---140141## Guardrails (critical, do not skip)142143- **Bounded.** Honor `--max-rounds` (default 5). If not approved by then, stop and144 surface why.145- **`NEEDS DISCUSSION` is a human gate.** Pause and ask; never invent a resolution146 for genuine ambiguity.147- **Corroborate, don't obey.** Per OCR's address step: verify each finding against148 the code; implement valid items; **decline wrong feedback with evidence**.149 Don't gold-plate: fix only what the review actually raised.150- **Prefer the structural fix** that makes a defect unrepresentable over151 correcting the instance. Correcting the instance is what feeds the next round a152 new blocker.153- **From round 2, brief the re-review as a re-review.** Tell the reviewers that154 the previous round's fix is the most likely source of this round's defect, and155 require a claim-by-claim table (claim → TRUE/FALSE → `file:line`) rather than a156 fresh prose read.157- **Never push red.** Before every commit, run the repository's own checks: the158 done-bar its agent instructions (`AGENTS.md` or equivalent) or contributing159 guide name, or else what its CI runs on a pull request (typically lint,160 typecheck, test, build), scoped to the change where the tooling can scope it.161 Fix failures before pushing. **A passing check is not coverage:** where a162 finding is about what code or a document _says_, corroborate it by reading it,163 not by re-running the checks.164- **Never force-push.** A shared PR keeps its history; corrections go on top.165- **Branch safety.** Refuse to run on the default branch; this skill commits and166 pushes.167- **Faithful reporting.** Report verdicts and outcomes honestly. If a blocker168 genuinely can't be fixed (it needs a product or architecture decision), stop169 and say so rather than forcing APPROVE.170- **New round, same session.** Each iteration is a new OCR review round in the171 same session (a closed session starts `round-{n+1}`), reusing172 `discovered-standards.md` and `context.md`.173174## Reference175176- `references/loop-mechanics.md`: per-round mechanics, verdict gating, session177 and round handling, the re-review brief, and the PR comment templates.