self-review-fix-loop

Overview

This skill runs an iterative review-and-fix loop over code changes. Each iteration has two waves of parallel agents: 3 reviewers that find issues, then 3 fixers that resolve them. The coordinator consolidates findings between waves and partitions work across fixers to avoid conflicts.

The loop continues until reviewers find no meaningful issues or the iteration cap (10) is reached.

Why self-review works: Automated self-review catches 80%+ of issues before human review because it applies multiple specialized lenses (correctness, security, maintainability) in parallel — something a single reviewer rarely does consistently. This reduces review cycles and unblocks PRs faster.

Step 1: Scope

Determine the review scope:

• If there is a git diff (staged + unstaged), that is the default scope
• Otherwise, use the provided feature scope or file list
• Identify the changed files, their purpose, and the intent of the changes

Step 2: Review (Parallel — 3 Agents)

Spawn 3 reviewer agents (Explore type, read-only) in parallel:

• Reviewer A: Requirement coverage and behavioral correctness
• Reviewer B: Regressions, edge cases, error handling, security/privacy, performance
• Reviewer C: Tests, maintainability, instruction/policy compliance

Each reviewer returns findings with severity (P0-P3), evidence, and fix direction.

Step 3: Consolidate

The coordinator merges, deduplicates, and normalizes severity across all reviewer outputs:

1. Merge findings from all reviewers
2. Deduplicate (same file + same issue = one finding)
3. Normalize severity across reviewers
4. Produce a single prioritized backlog
5. If the backlog is empty, the loop ends

Findings Packet Format

Write consolidated findings to .context/review-findings.json using the context packet standard (see references/orchestration/context-packet.md):

{
  "type": "review",
  "version": "1.0",
  "metadata": {
    "skill": "self-review-fix-loop",
    "project": "PROJECT",
    "created_at": "TIMESTAMP"
  },
  "payload": {
    "findings": [
      {
        "severity": "P0",
        "file": "src/api/users.ts",
        "description": "Missing auth check on DELETE endpoint",
        "fix_direction": "Add requirePermission guard before handler",
        "evidence": "Line 42: router.delete('/users/:id', handler) has no guard"
      }
    ]
  }
}