# Iterative Review > Plan → code → review → re-code feedback loop with persistent state across iterations. Spawns the review-coordinator, tracks findings across pushes, dedupes against prior iterations, and respects user "won't fix" decisions Use when this capability is needed. - Skill: `tomevault-io/iterative-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/iterative-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/iterative-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/iterative-review --- # Iterative Review — The Feedback Loop A sustained plan/code/review/re-code cycle on the current branch. Each pass: 1. Plans (or replans) the change 2. Implements the plan 3. Spawns `review-coordinator` to synthesize parallel reviewer findings 4. Persists findings to `.claude/state/review-state-.json` (append-only) 5. On the next pass, the coordinator sees prior findings and tracks fixed/unfixed/won't-fix This is the framework's primary inner loop for non-trivial work. Use `/team review` for one-shot reviews; use `/iterative-review` when you expect multiple iterations. ## Usage ``` /iterative-review — start or continue the loop on the current branch /iterative-review --plan-only — produce/refresh the plan; do not implement or review /iterative-review --review-only — skip planning + coding; just spawn coordinator /iterative-review --reset — discard state for this branch and start fresh /iterative-review --override [reason] — break glass; force APPROVE without review (tracked) ``` **Break-glass override.** For hotfixes when a real review would block a critical merge, `--override` tells `review-coordinator` to skip Steps 2–6, write a single APPROVE iteration to state with `"override": "break-glass"`, and exit. The override is tracked in `review-state-.json` for retrospective analysis. The next iteration without `--override` runs the full review normally. Equivalent: a comment containing `break glass` in the user's prompt to the skill triggers the same path. Use sparingly; review-coordinator's verdict rubric already biases toward APPROVE for legitimate cases. ## State Files All state lives in `.claude/state/` (gitignored). Per branch: | File | Purpose | Lifecycle | |------|---------|-----------| | `plan-.md` | The current implementation plan | Rewritten on `--plan-only` | | `review-context-.md` | Shared context every sub-reviewer reads | Rewritten by coordinator each iteration | | `review-state-.json` | Append-only findings history | Coordinator appends, never rewrites | Branch names with `/` are sanitized to `-` for filenames (e.g., `feature/auth` → `feature-auth`). ## Process ### Phase 1: Plan If `.claude/state/plan-.md` doesn't exist, or `--plan-only` was passed: 1. Read the ticket / user intent from the conversation context 2. Spawn the `architect` agent with prompt: "Produce an implementation plan for the current task. Identify changed surfaces, risks, and the minimum coherent scope. Output in markdown with sections: Goal, Changes, Risks, Out-of-scope." 3. Write architect's output to `.claude/state/plan-.md` 4. Show the plan to the user. If `--plan-only`, exit here. If the plan exists and `--plan-only` was not passed, read and reuse it. The plan stays stable across iterations unless the user explicitly refreshes. ### Phase 2: Implement Make the changes per the plan. This phase runs as the main agent (you), not a sub-agent — the user sees code as it lands. Apply project rules from `.claude/rules/` automatically. Run `{{TEST_COMMAND}}` and `{{FORMAT_COMMAND}}` as you go. If `--review-only`, skip this phase. ### Phase 3: Review (Coordinator) Spawn the `review-coordinator` agent: ``` Spawn review-coordinator on the current branch. It will: - classify the diff into trivial/lite/full - select sub-reviewers - spawn them in parallel - read prior state from .claude/state/review-state-.json - merge, dedup, filter their findings - append to state and render the consolidated report ``` The coordinator handles all sub-agent orchestration — do not spawn individual reviewers from this skill. ### Phase 4: Surface Verdict and Next Action Read the coordinator's report. Show the user: - **Tier and agents used** (so they know what was checked) - **Findings grouped by severity** (collapsed for nits) - **Verdict** (APPROVE / APPROVE_WITH_NOTES / REQUEST_CHANGES / NEEDS_DISCUSSION) - **Suggested next action:** - `REQUEST_CHANGES` → "Run `/iterative-review` again after addressing critical findings" - `APPROVE_WITH_NOTES` → "Optional improvements remain; run `/iterative-review` again or proceed to commit" - `APPROVE` → "Ready to commit" - `NEEDS_DISCUSSION` → list the disputed findings with developer pushback ### Phase 5: Iterate When the user runs `/iterative-review` again after making changes: - Coordinator reads prior `review-state-.json` - Findings that no longer reproduce → marked `fixed`, shown in "Resolved" section - Findings still present → carried forward - New issues introduced by the fixes → flagged as new The state file is append-only, so iteration history is preserved (useful for PR retrospectives). ## Caching-Friendly Prompt Shape Sub-reviewers and the coordinator are given prompts that follow this order to maximize prompt cache hit rate: 1. System rules (stable across all runs) 2. `CLAUDE.md` / `AGENTS.md` excerpts (stable across iterations on this repo) 3. `review-context-.md` (stable across all sub-agents within one iteration) 4. Prior findings state (stable per iteration) 5. Current diff or specific question (most volatile, last) Volatile data (timestamps, current SHA, random IDs) is always at the end. Never embed `Date.now()` or similar in the static prefix. ## Marking a Finding "Won't Fix" When the user disagrees with a finding, two ways to record it: **Option A — In the state file** (recommended, machine-readable): Edit `.claude/state/review-state-.json` and add to the top-level `user_decisions` map: ```json "user_decisions": { "src/auth.ts:42:auth-security:fail-open": { "status": "wont_fix", "reason": "Behind feature flag, not yet enabled in any environment" } } ``` **Option B — Tell the assistant in conversation**, and ask it to update the state file. The coordinator respects these on the next iteration and does not re-raise unless severity is `critical`. ## Edge Cases | Scenario | Behavior | |----------|----------| | No diff against base branch | "Nothing to review" — exit without spawning agents | | Coordinator fails | Show the partial output; user can retry | | `.claude/state/` is in gitignore but doesn't exist | Create it; warn if `.gitignore` doesn't list `.claude/state/` | | User switches branches mid-loop | New branch gets its own state file; old state stays put | | Plan in `plan-.md` is stale (e.g., user pivoted) | User runs `--plan-only` to regenerate | | State file grows large (many iterations) | Coordinator only loads the most recent iteration's findings + `user_decisions` for matching; full history is preserved but not parsed every time | ## Related - `review-coordinator` agent — the synthesizer this skill orchestrates (`templates/agents/review-coordinator.md`) - `docs/finding-schema.md` — finding schema every sub-reviewer emits - `/team review` — one-shot multi-agent review without state - `/develop` — the broader dev cycle (fetch ticket → implement → validate → PR); use `/iterative-review` *within* `/develop` for tight loops - `/factory` — end-to-end pipeline; calls `/iterative-review` automatically when more than one review pass is expected --- > Source: [BostonOrange/claude-code-framework](https://github.com/BostonOrange/claude-code-framework) — distributed by [TomeVault](https://tomevault.io).