| name | iterate-revision |
| description | Revise one manuscript section against the reviewer team until DONE, BLOCKED, or HALT. Loops `@paper-writer` ↔ `@reviewer` with a venue-specific reviewer brief, recording every iteration's issues + verdict to `reviews.json` and updating `paper.json.sections[name]` status / iter. The first OMCR engine — a worked example of how to compose `skills/orchestrate/phases/*` primitives into a domain-specific loop. Safe to re-run; safe to resume after BLOCKED or HALT. |
| writes | ["paper","reviews"] |
| cost_estimate_tokens | 24000 |
/iterate-revision
This engine runs the smallest viable orchestration shape: one section, one writer, one reviewer, looped until a verdict is reached. It is the proof the orchestration pattern works — Phase 2's four engines are mostly copy-and-vary on top of this one.
If you are reading this because Claude Code's skill auto-discovery surfaced it: invoke it via /iterate-revision <section-path>. Do not edit the manuscript or .claude/omcr-state/ by hand while a run is in flight.
When this skill is invoked, immediately execute the workflow below. Do not only restate or summarize these instructions back to the user.
Signature
/iterate-revision <section-path> [--max-iter N] [--venue VENUE] [--force] [--allow-tbd]
| Flag | Default | Purpose |
|---|
--max-iter | 3 | Hard cap. Reaching it without DONE/BLOCKED → HALT. Override via CLI or via ## Research stack field iterate_revision.max_iter. |
--venue | paper.json.venue | Reviewer strictness target. CLI wins; falls back to state; if neither is set, abort. |
--force | false | Bypass the status == approved early-exit. |
--allow-tbd | false | Proceed despite [TBD: markers in the section file, the per-section outline, or paper.json.hypothesis (Phase 1 decision Q2). |
Examples:
/iterate-revision sections/results.tex — defaults; venue from paper.json/iterate-revision sections/intro.tex --max-iter 5 --venue Nature/iterate-revision sections/abstract.tex --venue NeurIPS --force
The loop
phase 01 — precheck (guards: file exists, venue resolvable, no [TBD: blockers, not approved)
phase 02 — draft-or-revise (@paper-writer) ┐
phase 03 — review (@reviewer) │ repeated up to --max-iter
phase 04 — evaluate (verdict rule) ┘
phase 05 — finalize (user summary + _run-log.jsonl append)
Loop body is phases 02 → 03 → 04. The loop itself is driven by skills/orchestrate/phases/04-loop.md; this engine just hands it a dispatch plan and a verdict rule.
Phase execution
Execute phases sequentially. For each phase, read the linked file and follow its instructions exactly.
- Phase 1 — Precheck. Read
phases/01-precheck.md.
- Phase 2 — Draft or revise. Read
phases/02-draft-or-revise.md.
- Phase 3 — Review. Read
phases/03-review.md.
- Phase 4 — Evaluate. Read
phases/04-evaluate.md.
- Phase 5 — Finalize. Read
phases/05-finalize.md.
Phases 02 → 03 → 04 form the loop body. The orchestrate loop primitive runs them up to --max-iter times.
Composition
This engine imports the following primitives from skills/orchestrate/:
phases/01-state-read.md — read paper.json (phase 01 of this engine) and reviews.json (phase 02 of this engine, for last-review lookup).phases/02-dispatch.md — dispatch @paper-writer (phase 02) and @reviewer (phase 03) via the Agent tool with inlined persona bodies.phases/03-evaluate.md — apply the verdict rule defined below; record the reviews.json entry verdict.phases/04-loop.md — drive the writer + reviewer dispatch plan through up to max_iter iterations; own _run-log.jsonl writes; honor budget_tokens post-hoc.
This engine does not invent its own state-read, dispatch, or loop mechanics. If you find yourself replicating that logic inside a phase file, you're solving the wrong problem — fix the primitive, do not fork it.
Verdict rule
The verdict is computed at the end of each iteration's reviewer dispatch. Canonical rule (passed as a severity-threshold rule spec to orchestrate/phases/03-evaluate.md):
| iter | critical | major | result |
|---|
| any | ≥ 1 | any | BLOCKED — critical issue requires structural fix |
| < max | 0 | ≥ 1 | CONTINUE — loop another iteration |
| < max | 0 | 0 | DONE — section approved |
| = max | 0 | ≥ 1 | HALT — iterations exhausted, majors remain |
| = max | 0 | 0 | DONE — finished on the last allowed iter |
minor and nit issues never gate the verdict. They are logged to reviews.json and surfaced in the phase 05 summary.
The verdict drives paper.json.sections[name].status:
| Verdict | Status set |
|---|
| DONE | approved |
| BLOCKED | blocked |
| HALT | revising (left open so the user can resume) |
| CONTINUE | revising (loop continues) |
Cost model
Each iteration is 2 Agent-tool dispatches (writer + reviewer). With max_iter = 3, a typical run is ≤ 6 subagent calls. The cost_estimate_tokens: 24000 frontmatter field is a coarse upper-bound for /supervisor-drive budget gating (Phase 3 §6); actuals land in _run-log.jsonl post-hoc per Phase 0 decision §6.
Per-iter cost is dominated by the persona body inline (writer ~250 lines, reviewer ~200 lines) plus the section content. Long sections (>500 lines of LaTeX) compound this — the engine does not auto-trim; the user should split very long sections before running.
What this engine does NOT do
- Does not track which issues were "already fixed" across iterations. Only the most recent review is passed to the writer (Phase 1 decision Q1). The reviewer's iter-N+1 read is what catches regressions.
- Does not auto-call
verify-citation when the reviewer flags a missing citation. Citation flags land as ordinary major/minor issues; the writer addresses them next iter or leaves a [CITE: ...] placeholder for @literature-curator. (Phase 1 decision Q3 — deferred to Phase 2 /respond-reviewer.)
- Does not commit to git between iterations by default. Per-iter commit is an opt-in flag (passed to the loop primitive's
on_iter_end slot); OMCR currently leaves it off.
- Does not call another engine. Engines are leaves; if you need to chain, that is
/supervisor-drive's job in Phase 3.
- Does not rewrite
main.tex or any non-section file. The writer touches the section file only.
Re-running policy
- Already-approved section + no
--force → phase 01 exits cleanly, no agent calls.
- Already-approved section +
--force → phase 01 flips status to revising, the loop runs normally.
- BLOCKED section → phase 01 lets the run proceed; the user is expected to have addressed the critical issue manually before re-running. Iter counter continues.
- HALT section → phase 01 lets the run proceed; iter counter continues from where it left off.
[TBD: marker in the section / outline / hypothesis + no --allow-tbd → phase 01 sets status = blocked-on-tbd and exits, listing each marker's location.
See also
