review-fix-protocol
Use this when running the post-review fix loop after a review/devil/critic agent emits findings, when authoring a .findings.json file, when routing fixes to the responsible agent, or when deciding whe
SKILL.mdskills/review-fix-protocol/SKILL.md
GitHubReview-Fix Resolution Protocol
Overview
Every pipeline phase follows the same review-fix resolution loop after review agents produce findings. The loop tracks each issue individually (max 5 retries per issue), routes fixes to the correct agent, deduplicates across reviewers, and detects when the loop is stuck.
Structured Findings JSON Schema
Every review agent MUST produce a .findings.json file alongside their markdown report. This is the machine-readable input for the resolution loop.
Findings File Schema
{
"reviewer": "<agent-name>",
"phase": "<phase-name>",
"run_id": "<uuid>",
"iteration": 1,
"timestamp": "<ISO-8601>",
"findings": [
{
"id": "<PHASE-PREFIX>-<NNN>",
"severity": "blocker|high|medium|low",
"category": "<category>",
"title": "<short description>",
"description": "<detailed explanation>",
"file": "<file-path>",
"line": "<line-number or null>",
"fix_agent": "<agent-name that should fix this>",
"fix_action": "<specific action to take>",
"story_id": "<US-XXX if traceable, else null>"
}
],
"summary": {
"total": 0,
"blocker": 0,
"high": 0,
"medium": 0,
"low": 0
}
}
Finding ID Prefixes by Phase
| Phase | Prefix | Example |
|---|---|---|
| Architecture | AR |
AR-001 |
| Detailed Design | DD |
DD-001 |
| Implementation | IM |
IM-001 |
| Testing | TS |
TS-001 |
| Frontend | FE |
FE-001 |
| Cross-LLM Gemini sibling | <phase-prefix>-G |
IM-G-001, SD-G-001 |
| Cross-LLM contradiction (synthesized) | XL-CONFLICT |
XL-CONFLICT-001 |
Severity Definitions
| Severity | Definition | Resolution Requirement |
|---|---|---|
blocker |
Prevents the phase from being signed off | MUST fix — blocks report approval |
high |
Significant quality issue | SHOULD fix — degrades quality if left |
medium |
Improvement opportunity | FIX if possible within iteration budget |
low |
Minor suggestion | FIX only if trivial, else log as accepted |
Resolution Loop Algorithm
FUNCTION ResolutionLoop(phase, review_findings_dir, fix_agents_map):
// Step 1: Initialize issue tracker
issue_tracker = {} // keyed by finding ID
iteration = 0
global_max_iterations = 10 // safety cap for the loop itself
per_issue_max_retries = 5
stuck_threshold = 2 // consecutive non-improving iterations
// Step 2: Parse initial findings
all_findings = ParseAllFindingsJSON(review_findings_dir)
all_findings = Deduplicate(all_findings)
FOR each finding IN all_findings:
issue_tracker[finding.id] = {
finding: finding,
retry_count: 0,
status: "open", // open | fixed | ignored
history: []
}
// Step 3: Main loop
previous_open_count = len(all_findings)
consecutive_no_progress = 0
WHILE iteration < global_max_iterations:
iteration++
// 3a: Check exit — all resolved?
open_issues = [i FOR i IN issue_tracker.values() IF i.status == "open"]
IF len(open_issues) == 0:
RETURN "ALL_CLEAR"
// 3b: Filter issues that have NOT exhausted retries
fixable_issues = []
FOR each issue IN open_issues:
IF issue.retry_count >= per_issue_max_retries:
issue.status = "ignored"
issue.history.append({
iteration: iteration,
action: "ignored_after_max_retries",
reason: "Same issue persisted after 5 fix attempts"
})
LOG decision: "Ignoring {issue.id} after {per_issue_max_retries} retries"
ELSE:
fixable_issues.append(issue)
// 3c: Re-check exit after ignoring exhausted issues
IF len(fixable_issues) == 0:
RETURN "CONVERGED_WITH_IGNORED"
// 3d: Stuck detection
current_open_count = len(fixable_issues)
IF current_open_count >= previous_open_count:
consecutive_no_progress++
ELSE:
consecutive_no_progress = 0
IF consecutive_no_progress >= stuck_threshold:
LOG decision: "Stuck detection: findings not decreasing for {stuck_threshold} iterations"
FOR each issue IN fixable_issues:
issue.status = "ignored"
issue.history.append({action: "stuck_detected"})
RETURN "STUCK"
previous_open_count = current_open_count
// 3e: Route to fix agents
fix_groups = GroupByFixAgent(fixable_issues)
FOR each (agent, issues) IN fix_groups:
SpawnFixAgent(agent, issues, iteration)
FOR each issue IN issues:
issue.retry_count++
issue.history.append({
iteration: iteration,
action: "fix_assigned",
agent: agent
})
// 3f: Wait for fixes, re-run deterministic guardrails
WaitForAllFixAgents()
guardrail_result = RunGuardrails()
// 3f-gate: DETERMINISTIC-FIRST GATE (v1.1.0)
// Cheap deterministic guardrails run on every iteration. The expensive
// reviewer fleet (devil agents, simulated-human reviewers, code-reviewer-go)
// only spawns when guardrails are green. If any BLOCKER guardrail fails,
// synthesize the failures as findings and loop back to fix agents without
// paying the reviewer-fleet token cost for an iteration we already know
// needs another fix pass.
//
// Invariant preserved: every iteration that a reviewer fleet would have
// OBSERVED is still reviewed. Iterations we skip are ones where the code
// has known mechanical defects that would pollute reviewer findings
// anyway.
IF guardrail_result.has_blocker_fail:
synthesized = SynthesizeGuardrailFailuresAsFindings(
guardrail_result,
iteration=iteration
)
// Merge into issue_tracker using the same reconcile logic as reviewer findings
FOR each g_finding IN synthesized:
matching = FindMatch(g_finding, issue_tracker)
IF matching IS NULL:
issue_tracker[g_finding.id] = {
finding: g_finding,
retry_count: 0,
status: "open",
history: [{iteration: iteration, action: "guardrail_finding"}]
}
ELSE:
matching.finding = g_finding
matching.history.append({iteration: iteration, action: "guardrail_still_failing"})
LOG decision: "Deterministic-first gate: guardrail BLOCKER(s) — skipping reviewer fleet re-run, looping to fix"
CONTINUE // back to WHILE — next iteration re-routes to fix agents
// 3g: Re-run review agents (gate is green — guardrails PASS)
new_findings = ReRunReviewAgents()
new_findings = Deduplicate(new_findings)
// 3h: Reconcile — match new findings to existing issues
FOR each old_issue IN issue_tracker.values():
IF old_issue.status == "open":
matching_new = FindMatch(old_issue.finding, new_findings)
IF matching_new IS NULL:
old_issue.status = "fixed"
old_issue.history.append({iteration: iteration, action: "resolved"})
ELSE:
old_issue.finding = matching_new // update with latest details
old_issue.history.append({iteration: iteration, action: "still_open"})
REMOVE matching_new FROM new_findings
// 3i: Add genuinely new findings
FOR each new_finding IN remaining new_findings:
issue_tracker[new_finding.id] = {
finding: new_finding,
retry_count: 0,
status: "open",
history: [{iteration: iteration, action: "new_finding"}]
}
RETURN "MAX_ITERATIONS_REACHED"
Deterministic-First Gate (v1.1.0)
Why
Rule 13 (Post-Iteration Review Re-Run) requires the full reviewer fleet on every rework iteration. The fleet is expensive: 5+ devil agents × full-artifact input × per-agent decision-log writes. Running the fleet on code that hasn't even passed the deterministic gate (build, static analysis, leak check) wastes tokens — reviewer findings on broken code are dominated by the mechanical breakage and get superseded on the next iteration anyway.
The gate preserves Rule 13's correctness invariant: every iteration whose output a reviewer would meaningfully evaluate still gets reviewed. What it removes is reviewer-fleet spawn cost for iterations we already know are going to need another fix pass.
What counts as "deterministic"
BLOCKER checks that are 100% script-driven and produce PASS/FAIL without LLM judgment. In this pipeline:
- The active language adapter's build, vet, fmt, and static-analysis commands (
toolchain.build,toolchain.vet,toolchain.fmtfrom the package manifest) - The active adapter's test command (
toolchain.test), including race-detection if the language supports it - The active adapter's leak-check harness (
toolchain.leak_check) — surfaces as a guardrail in the leak-prevention category - The active adapter's supply-chain commands (
toolchain.supply_chain) — supply-chain guardrails (G32–G34) - Marker hygiene byte-hash checks (G95, G96, G98, G100, G103)
- Constraint-bench proofs (G97) — deterministic given pinned seeds
- License allowlist check (dep-vet, G33)
WARNING-severity guardrail failures do NOT trigger the gate — reviewer fleet proceeds.
Gate behavior
- After every fix batch, run the guardrail script fleet (cheap, parallel).
- If any BLOCKER fails: synthesize the failures into the findings schema (fix_agent = the agent that owns the failing domain per the phase's fix-agent map), merge into
issue_tracker, and loop back to fix-agent routing. Do not spawn the reviewer fleet this iteration. - If no BLOCKER fails: proceed to reviewer fleet re-run (current behavior).
Guardrail findings get IDs prefixed GR-<Gxx>-<iter> so they're distinguishable from reviewer findings in the issue tracker and report.
What the gate does NOT change
- Full-fleet reviewer re-run still happens on every iteration that reaches 3g.
- Per-issue retry cap (5), stuck detection (2), global iteration cap (10) apply unchanged — including to synthesized guardrail findings.
- Final-wave reviewer fleet before phase sign-off runs regardless (exit-gate reviewer run is not a rework iteration).
Observed cost shape
Reviewer-fleet spawn per iteration ≈ N_reviewers × avg_reviewer_tokens. Gate saves this cost on any iteration whose fix batch introduced a mechanical regression. In runs where the mechanical guardrails typically flag 30–40% of iterations, gate saves ~30–40% of the reviewer-fleet token spend at zero correctness loss.
Deduplication Logic
Multiple reviewers may flag the same issue. Before routing to fix agents:
- Group findings by
file+ approximatetitlematch (case-insensitive, ignoring articles) - If two findings target the same file and describe the same issue:
- Keep the one with HIGHER severity
- Discard the duplicate
- Log:
"Deduplicated: {id-kept} supersedes {id-discarded}"
- Cross-reviewer deduplication: If
frontend-code-reviewerflags "Missing error boundary" andsimulated-frontend-leadflags "Add Error Boundary" for the same file, keep the higher severity one
Fix Agent Routing
Each finding's fix_agent field determines who fixes it. The phase lead spawns fix agents with this exact format:
RESOLUTION FIX — Iteration {N}
You are being called to fix specific review findings. Do NOT run your normal generation flow.
FINDINGS TO FIX:
1. {id} ({severity}): {title}
File: {file}:{line}
Description: {description}
Action: {fix_action}
Retry: {retry_count}/{per_issue_max_retries}
RULES:
- Read ONLY the files listed above
- Fix ONLY the issues described
- Do NOT regenerate files from scratch
- Do NOT modify unrelated code
- Verify fix compiles/passes
- Log a "type":"refactor" entry per finding to the decision log
Fix Agent Mapping by Phase
Architecture Phase
| Category | Fix Agent |
|---|---|
| Service boundary issues | system-decomposer |
| API contract issues | api-designer |
| Database schema issues | database-architect |
| Infrastructure issues | infrastructure-architect |
| Design pattern issues | pattern-advisor |
Detailed Design Phase
| Category | Fix Agent |
|---|---|
| Component/interface design | component-designer |
| DTO/validation issues | interface-designer |
| Data model issues | data-model-designer |
| Algorithm issues | algorithm-designer |
| Concurrency issues | concurrency-designer |
| SDK design issues | sdk-designer |
| Coding guidelines | coding-guidelines-generator |
Implementation Phase
| Category | Fix Agent |
|---|---|
| Service code issues | code-generator |
| SDK package issues | sdk-implementor |
| Migration issues | migration-generator |
| Build/config issues | build-config-generator |
| Deployment issues | deployment-generator |
| Documentation issues | documentation-agent-go |
Testing Phase
| Category | Fix Agent |
|---|---|
| Unit test issues | unit-test-agent |
| Integration test issues | integration-test-agent |
| Contract test issues | contract-test-agent |
| E2E test issues | e2e-test-agent |
| Performance test issues | performance-test-agent |
| Security test issues | security-test-agent |
| Test data issues | test-data-agent |
Frontend Phase
| Category | Fix Agent |
|---|---|
| Component issues | component-generator |
| Page issues | page-generator |
| Form issues | form-generator |
| i18n issues | i18n-generator |
| State/DuckDB issues | state-architect |
| API hook issues | api-hook-generator |
| Config/build issues | frontend-build-config |
| WebSocket issues | websocket-handler |
Manifest Tracking Schema
Every phase lead tracks the resolution loop in the run manifest:
{
"resolution_loop": {
"status": "pending|in-progress|completed|stuck|converged_with_ignored",
"current_iteration": 0,
"max_global_iterations": 10,
"per_issue_max_retries": 5,
"stuck_threshold": 2,
"issue_tracker": {
"<finding-id>": {
"severity": "blocker",
"title": "...",
"fix_agent": "...",
"retry_count": 0,
"status": "open|fixed|ignored",
"ignored_reason": null
}
},
"history": [
{
"iteration": 1,
"open": 15,
"fixed": 0,
"ignored": 0,
"new": 0
}
],
"final_summary": {
"total_found": 0,
"resolved": 0,
"ignored_after_max_retries": 0,
"ignored_stuck": 0,
"open": 0
}
}
}
Convergence Criteria
The loop terminates when ANY of these conditions is met:
| Condition | Status | Report Impact |
|---|---|---|
| All findings resolved | completed |
APPROVE |
All remaining are ignored (max retries) |
converged_with_ignored |
APPROVE_WITH_CAVEATS (list ignored) |
| Stuck for 2 consecutive iterations | stuck |
NOT_READY (if blockers remain) |
| Global iteration cap (10) reached | max_iterations_reached |
NOT_READY |
Report Integration
Every phase's final report MUST include a Resolution Loop Summary section:
## Resolution Loop Summary
| Metric | Value |
|--------|-------|
| Total findings | 23 |
| Resolved | 20 |
| Ignored (max retries) | 2 |
| Ignored (stuck) | 1 |
| Iterations | 4 |
| Status | CONVERGED_WITH_IGNORED |
### Ignored Issues (accepted risk)
1. AR-007 (medium): "Missing retry logic in NATS publisher" — 5 fix attempts, pattern-advisor unable to resolve
2. AR-015 (low): "Cost estimate missing for Redis cluster" — stuck after 3 iterations
### Resolution History
| Iteration | Open | Fixed | Ignored | New |
|-----------|------|-------|---------|-----|
| 1 | 23 | 0 | 0 | 0 |
| 2 | 15 | 8 | 0 | 0 |
| 3 | 9 | 6 | 0 | 0 |
| 4 | 3 | 5 | 2 | 1 |
Review Agent Requirements
For this protocol to work, ALL review agents across ALL phases MUST:
- Produce a
.findings.jsonalongside their markdown report - Include
fix_agentfield on every finding - Include
severityfield on every finding - Use the standard finding ID prefix for their phase
- On re-run iterations, compare with previous findings to identify resolved vs. new