Iterate guide: review first, then decide whether to let the agent fix

Iterate guide: review first, then decide whether to let the agent fix

Iterate is for code tasks that benefit from repeated review, fixes, validation, and another review. A one-line edit usually does not need it. The skill can run in several coding assistants, but it also uses shell commands, reads and writes project files, and works with Git. Start with review-only; try the fixing modes later in a clean, isolated branch.

Version note (checked 2026-10-25): GitHub’s latest release and the npm installer are at 3.9.0, while ClawHub’s registry API still reports 3.8.2. The installer below fetches the latest GitHub release, so its version may temporarily differ from the version indexed by ClawHub. Do not mix behavior notes from the two versions.

Install: what the one-command installer does

The official installer supports Codex, Claude Code, Cursor, GitHub Copilot, and other clients. Check for Node.js 18+, Python 3.10+, tar, and GnuPG, then run this in a terminal:

npx iterate-skill-installer --ai codex

--ai codex selects Codex as the skill target. The installer also puts the iterate CLI on your PATH, preferring pipx and otherwise using pip --user. Review the selected client and destination before confirming; avoid duplicate installs. Add --no-cli if you only want the skill files, but you will need to install the CLI separately to run onboarding and deterministic checks.

The installer downloads an archive, a SHA256 manifest, and its signature from GitHub Releases, then verifies the checksum and GPG signature. If GnuPG is missing, install it and verify the signing key; do not disable verification just to continue. Keep the error details if installation fails instead of switching to an unknown mirror.

If you installed the CLI and want shell tab completion, version 3.9.0 adds an install command:

iterate completion zsh --install

It writes to the user’s zsh completion directory and refuses to overwrite an existing file by default. Read the help and inspect the target before choosing --force. This command is not part of the 3.8.2 file still reported by the ClawHub API at the time checked.

Onboard a project and check its configuration

In the terminal, enter the Git project you want to review:

cd /path/to/your-project
iterate onboard
iterate doctor

Onboarding scans project context and prepares ITERATE.md and iterate.config.yaml. Review the generated project map, protected areas, and validation.commands. Those commands can be run during later verification, so confirm each one is real and appropriate for your project before asking for fixes. iterate doctor checks onboarding and configuration; it does not mean the code has passed tests.

First task: produce a review report only

Pick a scope you can check manually, such as input validation and error handling in the recent changes. In a Codex conversation, call $iterate and explicitly request a read-only review; in other clients, use their skill invocation format with the same goal. Adapt this practice prompt:

Review only input validation and error handling in this project. Use review-only mode; do not fix code or create a branch. For each finding, report the file path, line, impact, and how to verify it. At the end, check the report's counts and evidence, and give the final verdict.

Iterate’s review-only / dry-run skips the fix loop and produces a report with convergence details, a meta-review, and an approved or needs_revision verdict. Check that each path and line exists and that the recommendation fits the code. Version 3.9.0’s instructions allow one report record to be written to .iterate_decisions.md; this means “do not change code,” not “guaranteed zero writes to the worktree.” Compare git status --short before and after.

Let it make changes only after you understand the workflow

For a feature, bug fix, or refactor, save existing work and use a clean, isolated worktree or branch before giving a concrete objective:

Use defensive mode to add email-format validation to the settings page. Check project constraints and existing tests first. Make minimal changes and run the verified validation commands after each step. At the end, report changed files, test results, unresolved items, and the branch name. Do not merge or push.

In compatible clients, invoke $iterate defensive with the goal; clients that use slash-style skill commands use their own form of /iterate defensive <goal>. Defensive mode runs a pre-check, makes minimal edits with post-checks, then checks project invariants and uses the multi-round review loop as a delivery gate. If an onboarded project has no validation commands configured, the guard fails closed. Add real checks to iterate.config.yaml before continuing; do not bypass the failure.

Use ordinary /iterate <goal> for a broader closeout task: review, classify fixes, validate, and review again until convergence. Atomic issues may be fixed automatically; architectural changes require user approval under the instructions. Merge and push are off by default. Do not run an autonomous fixing mode on an unisolated working tree or on high-risk areas such as authentication, payments, or production data.

How to check the result

Do not stop at a “done” summary:

1. Read the final report. Check evidence paths, line numbers, severity, and the convergence rounds. 0 findings means no new issues were found in that run; it does not prove the code is defect-free.
2. Check the meta-review verdict and evidence validation. If it says needs_revision, resolve contradictions or invalid evidence first.
3. In the terminal, inspect git status --short and git diff. Confirm that changes stay on the intended isolated branch and that no unexpected or sensitive files appeared.
4. Run the project’s tests, lint, or build yourself and confirm the report’s validation commands actually ran and passed. Agent output does not replace CI or a human review.
5. Read the changed code before deciding whether to cherry-pick, merge, or push. “Converged” does not mean “ready to deploy.”

Common problems

• The first invocation asks for onboarding: Review the project context and configuration; this is not a hang. Onboarding writes files.
• Defensive mode refuses to start: Check the failed iterate guard pre-check items. Common causes include a dirty worktree, missing validation commands, or an executable not being on PATH.
• A validation command fails: Confirm the configuration matches the project scripts. Do not let the agent turn a failing test into a skipped test to manufacture a green result.
• A report citation looks questionable: Check the real file and line. Ask for a fresh review if evidence is missing; do not turn a guess into a bug report.
• The run takes too long: Limit the task to one module or a specific change set and use a reasonable round limit. A full-project, multi-dimension review can take longer.
• The command does not match your client: The installer places the skill and CLI; the host assistant decides how skills are invoked. Codex has its own skill entry point, so do not copy another client’s command verbatim.

Is it a fit?

If you only need a scoped review prompt, Matt Pocock’s code-review skill is a narrower reference. Iterate’s distinction is its combination of a read-only report mode, a fix-and-review loop, and defensive incremental coding. Neither replaces your own tests and approval.

This guide is based on the official documentation and release notes. It does not claim a QClawHub hands-on run or an independent user success case.

Sources

• ^[1]
• ^[2]
• ^[3]
• ^[4]
• ^[5]
• ^[6]