iterate-revision

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

1. Phase 1 — Precheck. Read phases/01-precheck.md.
2. Phase 2 — Draft or revise. Read phases/02-draft-or-revise.md.
3. Phase 3 — Review. Read phases/03-review.md.
4. Phase 4 — Evaluate. Read phases/04-evaluate.md.
5. 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

• ../orchestrate/SKILL.md — the 4 primitives this engine composes.
• ../../wiki/Orchestration-Model.md — public pattern doc.
• ../../develop/example-state/README.md — state-file schema reference.
• ../../develop/phase-1-iterate-revision.md — full design rationale + acceptance scenarios.
• ../../develop/phase-1-decisions.md — the three locked Phase 1 decisions (Q1, Q2, Q3) with rationale.