build-until-pass

name: build-until-pass description: Use when a build, typecheck, lint, or test command is failing and you want the agent to drive it to green on its own — run the check, read the errors, apply the smallest fix, re-run, repeat until exit code 0. Stops the human from being the while-loop (run → read error → fix one line → run again) and stops the agent from bulldozing huge speculative rewrites between checks.

Build Until Pass

A bounded self-correcting loop: run the project's check command, capture its errors, apply the smallest diff that addresses the first failure, re-run, and repeat until it exits 0 — or until a hard attempt cap is hit.

The core principle: the check command is the judge, not you. You do not declare the build "basically fixed." Green is exit code 0. Anything else is red, and red means another round.

This is the engineering-discipline counterpart to "run it and hope." The cap exists so the agent backs off instead of burning tokens thrashing on an error it cannot fix without human input.

When to Use

• A build / compile / bundle command fails and the cause is mechanical (type errors, missing imports, signature mismatches, bundler config)
• tsc, cargo build, go build, npm run build, vite build exits non-zero
• A typecheck or lint gate is red and you want it green before committing
• A focused test suite is failing and each failure points at a clear fix
• CI went red on a build/typecheck step and you're reproducing locally
• You catch yourself copy-pasting errors back to the agent one at a time

When NOT to Use

• You don't know the check command yet — find it first (see Phase 0)
• The failure is a genuine logic bug needing investigation, not a mechanical fix → use debug-hypothesis instead, then come back here to confirm green
• The fix requires a product/design decision only a human can make
• The "fix" would mean deleting tests, // @ts-ignore-ing real errors, or loosening types to silence the compiler → that's cheating the judge, not passing it (see Anti-rationalizations)
• The build passes already — there's nothing to loop on

The Loop

            ┌─────────────────────────────────────────────┐
            │  attempt > MAX_ATTEMPTS (default 10)?        │
            │  → STOP, report what's left, ask the human   │
            └──────────────────────┬──────────────────────┘
                                   │ no
   RUN CHECK ──▶ green? ──yes──▶  DONE (exit 0, report rounds used)
       ▲             │
       │             │ no (red)
       │             ▼
       │      READ ERRORS  ──▶  FIX SMALLEST  ──▶  re-RUN
       │      first failure     minimal diff,        │
       │      only, verbatim    no refactor          │
       └──────────────────────────────────────────────┘
                    one round = one fix + one re-run

Hard rules:

1. Green is exit code 0 from the check command. Not "looks fixed," not "the error I saw is gone." Run it and read the exit status.
2. One round = one targeted fix + one re-run. Do not fix five unrelated things, then run once. You won't know which fix helped or broke something.
3. Minimal diff per round. Touch only the lines the current error points at. No drive-by refactors, no reformatting, no renaming.
4. Hard attempt cap (default 10). When hit, STOP and hand back to the human. Do not raise your own cap to "just try a few more."
5. Report each round. One line: round N/MAX — <errors remaining> — <what I changed>.
6. Never silence the judge. Suppressing an error (@ts-ignore, any, deleting a test, || true) is not a pass. See Anti-rationalizations.

Phase 0: LOCK THE CHECK COMMAND

Goal. Know exactly what command defines "green" before you touch any code.

Steps.

1. Identify the check command. Look at, in order: the user's instruction, the project's CI config (.github/workflows/*), package.json scripts, Makefile, justfile, the build tool's convention.
2. If multiple are plausible (build vs typecheck vs test), pick the one the user named; if unstated, pick the narrowest one that reproduces the reported failure, and state your choice.
3. Run it once, unmodified, to capture the baseline failure and confirm it actually fails. A check that already passes means there's nothing to do.
4. Set MAX_ATTEMPTS (default 10 unless the user gave a number).

Exit criteria.

• Exact check command written down (copy-pasteable)
• Baseline run captured — confirmed non-zero exit
• MAX_ATTEMPTS set

Common Rationalizations

Phase 1: RUN CHECK

Goal. Get the current ground truth: exit code + full error output.

Steps.

1. Run the locked check command. Do not modify flags between rounds — same command every round, or the judge moved.
2. Read the exit code. 0 → jump to Done. Non-zero → continue.
3. Capture the error output. If it's long, focus on the first error block — later errors are often downstream of the first and vanish once it's fixed.

Exit criteria.

• Check command run unmodified
• Exit code read explicitly (not inferred from log text)
• First failure identified verbatim (file:line + message)

Phase 2: FIX SMALLEST

Goal. Apply the minimum change that resolves the first failure.

Steps.

1. Locate the first error's file:line. Read the surrounding code.
2. Apply the smallest correct fix: add the missing import, fix the type, match the signature, correct the path. Real fixes only — see the cheating list.
3. Change one logical thing. If the same root cause produces N identical errors across files (e.g. a renamed export), fixing the root and the N call sites is one logical change — that's allowed. Five unrelated fixes is not.
4. Do not touch anything the error didn't point at. Resist refactoring.

Exit criteria.

• Fix targets the first failure's root cause
• Diff is minimal — no unrelated edits, no reformatting
• No error was suppressed to fake a pass

Common Rationalizations

Phase 3: RE-RUN & GATE

Goal. Decide: done, another round, or stop and escalate.

Steps.

1. Re-run the check (back to Phase 1's command).
2. Green (exit 0)? → Done. Report total rounds used.
3. Red, and attempt < MAX_ATTEMPTS? → Report this round, loop to Phase 1.
4. Red, and attempt == MAX_ATTEMPTS? → STOP. Do not raise the cap.
5. Error unchanged after your fix, or oscillating (error A → fix → error B → fix → error A)? → STOP early. The loop is stuck; a human or debug-hypothesis is needed. Don't spend the remaining rounds thrashing.
6. Progress check: if the count of errors isn't trending down across rounds, treat it like step 5 — you're not converging.

Report format (one line per round):

round 3/10 — 4 errors left (was 7) — fixed missing `await` in db.ts:42

Exit criteria.

• Re-run executed with the unmodified command
• Exit code checked, not assumed
• Either green-and-done, or looped, or stopped-and-escalated — never silently continuing past the cap

Common Rationalizations

When the Loop Stops Red

Hitting the cap (or stopping early) is a legitimate, expected outcome — not a failure of the skill. Report:

1. The exact command and its final exit code.
2. The remaining errors (verbatim first block).
3. What you tried each round and why it didn't converge.
4. Your best hypothesis for why it's stuck (missing dep, env mismatch, a real logic bug, an API change that needs a design call).

Then hand back. A human unblocking one root cause is faster than the agent blindly trying fix #11.

Verification

The skill was applied correctly when:

• The check command was locked and run unmodified every round
• Each round was one targeted fix + one re-run, with a one-line report
• No error was suppressed, no test deleted, no type loosened to fake green
• The loop ended in exactly one of: green (exit 0), cap reached, or stopped early for non-convergence — with a final report either way
• If green: a final clean run of the command shows exit code 0
• If red: remaining errors + a hand-back hypothesis were reported

The Anti-Thrash Rule

The two failure modes this skill guards against:

• Human-as-while-loop — you copy an error to the agent, it fixes one line, you copy the next error, forever. Automate the loop, cap it, walk away.
• Agent-as-bulldozer — the agent writes a 200-line speculative "fix" between runs, it doesn't work, so it writes another 200 lines. Minimal diff per round + the cap kill this.

Run the judge. Read the first error. Fix the one thing. Run again. Stop at the cap.