Review Fix Loop

Local-first fresh re-review contract for AI agents.

Review Fix Loop prevents stale-diff reuse in AI review/fix/re-review loops. After an AI agent fixes findings, the next review pass must start from a fresh live snapshot of the Git worktree, selected gates, and durable redacted run records.

Why It Exists

AI coding agents often work in loops:

1. review the current diff;
2. fix findings;
3. re-review to decide whether the work is done.

The failure mode is subtle: pass 2 can accidentally reuse pass 1 diff text or pass 1 findings after files have changed. That makes the re-review stale. Review Fix Loop turns the loop into a local contract: every pass reloads changed slices from the live repository before the agent reasons again.

What Makes It Different

Tool type	Primary job	Fresh snapshot after fixes	Local-first	Boundary
Hosted PR bot	Review pull requests in a hosted service	Depends on the bot workflow	Usually no	External service, account, and repository permissions
reviewdog / pre-commit	Run diagnostics and hooks	Not the main contract	Yes	Great for checks, not a re-review loop protocol
Review Fix Loop	Govern AI review/fix/re-review loops	Yes	Yes	No hosted bot, no model API, no external service

5-Minute Quickstart

Run these commands from this repository checkout, or from a target repository that already contains the referenced adapter file. For another repository, copy adapters/project-template first or pass an absolute config path.

python -m pip install -e ".[dev]"

Initialize a target repository with the bundled generic adapter:

review-fix-loop init --repo . --output review-fix-loop.gates.json
review-fix-loop validate-config --repo . --config review-fix-loop.gates.json

Create a pass 1 snapshot and write local run records:

review-fix-loop snapshot \
  --repo . \
  --config review-fix-loop.gates.json \
  --mode normal_loop \
  --pass 1 \
  --write-run-record \
  --cache-dir .review-fix-loop

Run gates selected by that snapshot:

review-fix-loop gate \
  --repo . \
  --config review-fix-loop.gates.json \
  --snapshot .review-fix-loop/runs/<run-id>/snapshot.json

After fixing code, create pass 2 from the previous run record:

review-fix-loop snapshot \
  --repo . \
  --config review-fix-loop.gates.json \
  --mode normal_loop \
  --pass 2 \
  --previous-run-record .review-fix-loop/runs/<run-id>/run-record.json \
  --write-run-record \
  --cache-dir .review-fix-loop

Reusing pass 1 diff text or pass 1 findings without this fresh snapshot is an invalid workflow.

Useful local inspection commands:

review-fix-loop doctor --repo . --config review-fix-loop.gates.json
review-fix-loop inspect --snapshot .review-fix-loop/runs/<run-id>/snapshot.json
review-fix-loop validate-schema --schema snapshot --file .review-fix-loop/runs/<run-id>/snapshot.json

Who It Is For

• AI coding agent power users working with Claude, Codex, Cursor, Aider, or similar local workflows.
• Privacy-sensitive teams that want review-loop governance without uploading source to a hosted reviewer.
• Workflow-governance maintainers who need repeatable rules for snapshot, gate, and run-record handling.
• Adapter authors who want project-specific gates without rewriting the core loop contract.

How It Works

live Git worktree -> snapshot -> agent review -> fixes -> gates -> fresh snapshot -> re-review

Snapshots separate staged, unstaged, untracked, and branch-diff scopes. Slices are invalidated when their hashes, rule files, or gate config change. Run records keep durable metadata while avoiding full source text, full diffs, secrets, and unredacted command output. Gate diagnostics can be filtered to changed files, added lines, or diff context lines, and parsers support exit code, git diff --check, regex lines, JSON diagnostics, RDJSON, SARIF, and Checkstyle XML.

Current Boundaries

Review Fix Loop is not a hosted PR bot, not a GitHub App, not a hook framework, and not a model service. It does not require GitHub App credentials, cloud sandboxes, model API keys, or external services.

Documentation

• Quickstart
• Architecture
• Adapters
• Comparisons
• Contracts
• Deep research execution plan
• Remaining work implementation plan
• Review loop runbook
• Template repository guide
• FAQ
• 简体中文

Development

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m pytest -q --cov=review_fix_loop --cov-branch --cov-report=term-missing
.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m mypy src/review_fix_loop
.\.venv\Scripts\python.exe -m bandit -r src/review_fix_loop
.\.venv\Scripts\python.exe -m pip_audit
.\.venv\Scripts\python.exe -m build
.\.venv\Scripts\python.exe -m twine check dist/*

The runtime package has no install-time dependencies. Development extras are only for tests, quality checks, security checks, and release checks. Use an isolated virtual environment for development; uv-managed or otherwise externally managed Python installations may reject direct editable installs under PEP 668.