SuperAPI AI Directory

fix-loop

General & other

View repository

Updated 10-16 03:47

About this skill

Fix Loop

A bounded fix-and-verify protocol for resolving confirmed findings from a review pass. Prevents infinite loops by capping attempts and escalating to the user.

When to use

After a two-pass-review (or any review) produces confirmed P0/P1 findings that need fixing. Also after test failures that need code or test fixes.

Protocol

Input

  • Findings: confirmed P0/P1 findings conforming to the Output Schema below
  • Artifact paths: files to fix
  • Criteria: the original criteria the fix must satisfy

Intake filter: Only process findings where verdict = "confirmed" and severity in ["P0", "P1"]. Ignore P2/P3 findings — they are out of scope. Note: findings with verdict: "confirmed" are accepted regardless of source — the caller is responsible for confirmation quality (e.g., plan-runner sets this as an orchestrator escape hatch for per-wave review findings that have no verifier pass).

Round 1 — Fix

For each finding (or batch of related findings that affect the same files):

  1. Spawn a fix subagent (Sonnet for scoped fixes, Opus for cross-file fixes)
  2. Subagent receives: the finding (full schema), the affected file path(s), the criterion it violates
  3. Subagent fixes the code and returns: { files_changed: [paths], summary: string, concerns: [string] | null }
  4. Stage the changes (git add <specific files>) — do NOT commit. User decides when to commit.

Round 1 — Verify (targeted)

Deterministic check — confirm the specific finding is resolved without spawning an agent:

  • If tests exist: rerun the relevant test(s)
  • If code pattern: grep/read the specific lines to confirm the fix
  • If behavioral: spot-check the fixed code against the criterion

If the finding is resolved and no obvious new issues: done. If the finding persists or new issues are apparent: proceed to Round 2. If verification cannot run (flaky test, missing env, tool failure): treat as inconclusive. Use the AskUserQuestion tool with options: "Retry verification", "Accept fix without verification", "Revert and escalate". Recommended: "Retry verification". Do not count as a failed attempt.

Round 2 — Fix + Verify (full)

  1. Fix: spawn another fix subagent with context about what Round 1 attempted and why it didn't work
  2. Stage the changes (git add <specific files>)
  3. Verify: spawn the verifier agent with:
    • Artifact: the staged diff scoped to this finding's files (git diff --staged -- <files_changed>)
    • Findings: the original finding being fixed
    • Criteria: the original criterion the finding violated + "no new P0/P1 regressions introduced"
    • Scope: files changed in the fix
    • Output contract: "Return a ReviewOutput envelope (see Output Schema). Set verdict to confirmed/demoted/rejected with evidence on all findings."
  4. If the verifier finds new P0/P1 issues: escalate (do not attempt Round 3)

Escalation

If Round 2 still has unresolved P0/P1:

  • STOP. Do not attempt Round 3.
  • Present to the user:
    1. The original finding
    2. What was attempted in Rounds 1 and 2
    3. What's still broken and why
    4. Use the AskUserQuestion tool with options: "Manual fix", "Try a different approach", "Defer this finding". Recommended: "Defer this finding"

Rules

  • Max 2 attempts. Never loop beyond Round 2.
  • Scoped fixes. Fix subagents must NOT edit files outside the scope of their finding without user approval. If a fix requires additional files, the subagent must FIRST return { needs_scope_expansion: true, additional_files: [paths], justification: string } instead of making edits. The parent then uses the AskUserQuestion tool with options: "Approve expanded scope", "Reject — fix within original scope only", "Defer this finding". Recommended: "Approve expanded scope" (include the justification and file list). On approval, re-dispatch the subagent with expanded scope. Additional files are included in verification.
  • Always verify. Every fix must be verified. Don't assume a fix worked — check.
  • Batch related findings. Group related findings into one fix pass when they affect the same file(s).
  • Test failures. Determine if it's a code bug or test bug first, then fix the right one.
    • Code bug: fix implementation, rerun test
    • Test bug: fix test, rerun test

Output Schema

Finding

Finding {
  id: sequential number starting from 1,
  severity: "P0" | "P1" | "P2" | "P3",
  title: short title,
  body: detailed explanation with evidence,
  file: file path or null for global issues,
  line_start: number or null,
  line_end: number or null,
  confidence: 0.0-1.0,
  criterion: what was violated,
  verdict: "confirmed" | "demoted" | "rejected" | null,
  evidence: reasoning for verdict | null
}

ReviewOutput

Findings are wrapped in a ReviewOutput envelope:

ReviewOutput {
  schema_version: "v1",
  findings: Finding[],
  checks_run: string[]
}

Severity calibration

  • P0 — Must fix: breaks functionality, security breach, data loss, or violates criteria
  • P1 — Fix before shipping: correct but incomplete, fragile, or reliability risk
  • P2 — Should fix: quality issue, code smell, not blocking
  • P3 — Nice to have: observation, style, minor improvement

Field notes

  • confidence — 1.0 means certain, below 0.5 means you're guessing. Be honest.
  • criterion — required for P0/P1 findings. Name the specific criterion violated.
  • verdict — populated by the verifier in two-pass review. Set to null when producing findings directly.
  • evidence — verifier's reasoning for the verdict. Set to null when producing findings directly.
  • checks_run — list every criterion evaluated, file path checked, or acceptance criterion verified. For ACs, use AC-N: PASS — [evidence] or AC-N: FAIL — [reason].