Machines miss. A build can pass the plan and still produce a page with no buttons, or one that scrolls sideways on a phone. The repair pass exists so a near-miss does not become your problem to describe from scratch.
What triggers it
Any single failed check in the browser gate. The gate is strict on purpose: seven of eight passing is a failed build, because the eighth is usually the one a visitor notices.
What it is told
The repair agent receives the original brief, the approved plan, and the failed checks with the value each one measured. Not “something is wrong”, but for example:
Interactive elements reachable — No links, buttons, or form controls found
A measured value gives the agent something to fix. A vague complaint gives it something to guess at, and guessing is how a page gets rewritten when it only needed a button.
Exactly one pass
One repair run, then the gate runs again. If it passes, the build is done and the artifact is exported. If it still fails, the build is marked as needing another pass and the run stops.
There is no silent retry loop, for two reasons. It burns your model quota without asking. And a build that fails twice usually means the brief was ambiguous, which no amount of retrying fixes.
A real example
The reference build in these docs failed its first gate on exactly one check: the page had no interactive elements. The repair pass added a nav and a contact form, the gate re-ran, and all eight passed. The log read:
FAIL Interactive elements reachable — No links, buttons, or form controls found
Repair pass started (1 failed check(s))...
Repair done
Re-running the browser-test gate...
PASS Interactive elements reachable — 4 of 4 visible
Reported: browser test passed after repair.That is the intended shape of a near-miss: a specific complaint, a small fix, a re-measure.
When to repair it yourself instead
- The plan was wrong. If the approved steps describe the wrong product, repairing the output is wasted work. Start a new build with a better brief.
- The failure is a missing dependency. A page that needs a file the workspace does not have will fail the same way twice.
- You want to keep the current files. Repair edits the workspace. The checkpoint is still there, so this is recoverable with
rewind, but see Checkpoints and rewind first.

