/iterative-review

← Back to index

Summary

Spawns multiple devil's advocate agents in parallel to review a target, then spawns fix agents to address all moderate-or-above issues, re-runs tests after each fix pass, and repeats until no critical, major, or moderate issues remain.

When to use

Use /iterative-review when you want review and automatic fixes applied in a loop — not just a flaw list. It keeps cycling until no critical, major, or moderate issues remain.

Key distinction from /da-review: /da-review identifies problems and stops — you fix them yourself. /iterative-review identifies and fixes all moderate-or-above issues automatically, re-running tests between each cycle. Choose /da-review when you want control over the fixes; choose /iterative-review when you want problems resolved automatically.

Typical trigger situations:

Invocation

Pass a target as the argument. If no argument is supplied, the skill reviews the current uncommitted changes (git diff HEAD).

/iterative-review [target]

Parameters:

Loop behavior: Each cycle spawns a minimum of 3 DA agents reviewing from different angles (correctness/edge cases, architecture/design, test coverage gaps). Issues are labelled with severity and a cycle-prefixed ID (e.g., C1-I-1). Fix agents address all Critical, Major, and Moderate findings. The loop stops when the consolidated issue list contains no Critical, Major, or Moderate items — or when the same root-cause issues reappear unchanged across cycles (unresolvable oscillation). When the optional /brooks-review command (Brooks-Lint) is installed, each cycle also spawns one Brooks-Lint reviewer whose findings — labelled C1-B-1, C1-B-2, … — are consolidated and fixed alongside the DA findings; the command checks at startup and tells you whether it found /brooks-review or is proceeding with the DA agents only.

Clean code catalog pass (cycle 1 only): When /clean-code-review is installed and the target is code (uncommitted changes, a git ref/range, or source file paths), cycle 1 also runs one /clean-code-review pass — its 132 structured checks across 7 groups, findings labelled C1-CC-1, C1-CC-2, … and fixed alongside the rest. It runs in its own freshly spawned general-purpose agent, in the same parallel batch as the devil's advocate agents: /clean-code-review is itself a fan-out orchestrator that spawns its own 7 group agents plus a synthesizer, so it needs the agent-spawning and skill-invoking ability that only general-purpose has — which is why it is not delegated to a devils-advocate reviewer. It deliberately does not repeat in later cycles: from cycle 2 on, the loop is driven by the DA agents and the Brooks-Lint reviewer. The command tells you at startup whether it is running or skipped (not installed, or target is not code).

Severity rubric:

Note: Fix agents do NOT create git commits — all changes remain as uncommitted working-tree modifications.

Note on continuation: When invoked as a skill from /implement, the calling skill includes its own "do not stop at the review verdict" reminder in its NEXT-mode Step 3 — and /iterative-review itself also ends every Review Summary with a ⚠️ CALLER warning that the summary is not a task completion signal and the caller must continue to the next step immediately. Both the caller and the invoked skill carry a continuation reminder.

Example 1 — Auto-fix issues in a feature diff (illustrative example)

Input:

/iterative-review $(git diff HEAD)

Output / Result (after 2 cycles):

## Cycle 1 — DA findings (3 agents)
Critical C1-I-1: `save_order()` called before payment confirmed — order can be
  saved without charge.
Major    C1-I-2: No rollback on partial failure between charge and order save.
Moderate C1-I-3: Retry count hardcoded to 3; should be env-configurable.

## Cycle 1 — Fixes applied
C1-I-1 fixed: moved `save_order()` call after payment confirmation check.
C1-I-2 fixed: added try/finally block with rollback on charge success + save failure.
C1-I-3 fixed: replaced magic number with MAX_RETRY env var (default 3).

Tests: 42 passed, 0 failed.

## Cycle 2 — DA findings (3 agents)
(no Critical, Major, or Moderate issues found)

## Review Summary
### Verdict
No critical, major or moderate issues remain.
### Remaining Open Issues
- Minor N1: variable `tmp` in line 47 could be renamed for clarity (not auto-fixed).

Example 2 — Review a plan file and fix gaps (illustrative example)

Input:

/iterative-review plans/FEAT-007-payments.md

Output / Result:

## Cycle 1 — DA findings
Major C1-I-1: Task 3.2 adds a `/refund` endpoint but no task covers updating
  ledger records on refund — creates an inconsistency in accounting reports.
Major C1-I-2: No rollback task defined if the DB migration in Task 4.1 fails.
Moderate C1-I-3: Acceptance criteria for Task 2.3 omit rate-limiting the
  charge endpoint.

## Cycle 1 — Fixes applied
C1-I-1 fixed: added Task 3.3 "Update ledger on refund" to the plan.
C1-I-2 fixed: added Task 4.2 "Rollback plan for DB migration failure".
C1-I-3 fixed: added rate-limit acceptance criterion to Task 2.3.

## Cycle 2 — DA findings
(no Critical, Major, or Moderate issues found)

## Review Summary
### Verdict
No critical, major or moderate issues remain.
### Changes Made
- C1-I-1 → Major → added Task 3.3 to plan
- C1-I-2 → Major → added Task 4.2 to plan
- C1-I-3 → Moderate → tightened Task 2.3 acceptance criteria

Related tools