The fix loop — scan, prompt, iterate to zero

After wcag-audit scan finishes, the real work happens in your AI editor. Open WCAG_FIXES.prompt.md, let the editor run the embedded protocol, and re-scan to verify. Most projects reach zero actionable findings in 1–2 passes.

What the fix loop is

The CLI produces a file called WCAG_FIXES.prompt.md — not a report to read, but a self-contained protocol your AI editor executes. Open it in Claude Code, Cursor, Windsurf, or any agent-capable editor and instruct it to follow the protocol. The editor reads each finding, fixes the source, then re-scans to verify.

The loop looks like this:

1. Scan. wcag-audit scan audits every route and writes WCAG_FIXES.prompt.md.
2. Fix. Open the prompt file in your AI editor. It runs the embedded protocol and fixes issues across your codebase.
3. Verify. The editor runs wcag-audit verify --rc <id> after each fix to confirm it landed correctly.
4. Repeat. Re-scan. Most remaining findings are resolved in one more pass. Stop when findings are zero or you've dismissed the remaining noise.

$ wcag-audit scan
✓ 47 routes audited → 180 findings (23 critical, 44 serious, 113 moderate)
→ WCAG_FIXES.prompt.md written

# Open WCAG_FIXES.prompt.md in Claude Code / Cursor / Windsurf
# Editor runs the protocol, fixes source files

$ wcag-audit scan
✓ 47 routes audited → 12 findings (0 critical, 2 serious, 10 moderate)
→ WCAG_FIXES.prompt.md written

# Dismiss 1 false positive, fix the remaining 11
$ wcag-audit scan
✓ 47 routes audited → 0 actionable findings

Multi-Agent vs Linear protocols

The generated prompt detects what your editor supports and selects the right execution strategy automatically.

Multi-Agent Protocol

Used by Claude Code and other editors that support parallel sub-agents. The orchestrator reads the task manifest (.wcag-audit/task-manifest.json), which groups findings by source file. It then dispatches one file-owner sub-agent per source file in parallel. Each worker independently edits its file and returns a structured result:

{
  "rcId": "rc-abc123",
  "status": "fixed",
  "verifyExitCode": 0,
  "filesTouched": ["src/components/nav.tsx"]
}

After all workers finish, a verifier sub-agent reviews the results, checks for regressions across files, and produces a summary. Because workers run in parallel, a 40-file project that would take 20+ minutes sequentially typically finishes in 3–5 minutes.

Linear Protocol

Used by Cursor, Windsurf, and any single-agent IDE. The editor processes findings one at a time. After each fix, it runs wcag-audit verify --rc <id> to confirm the specific finding is resolved before moving to the next. Slower, but equally correct — and better for editors that don't support concurrent tool calls.

Stop criteria — the 3-attempt cap

Both protocols stop when one of these conditions is met:

• The task manifest is fully cleared (all findings resolved) and no regressions were introduced, or
• 3 fix attempts have been made.

After the third attempt, the agent writes FIX_REPORT.md at your repo root. It lists which findings landed, which didn't, and why — including any errors or cases where the verify step kept failing. There is no silent partial success: if something didn't get fixed, it appears explicitly in the report.

The needs-design batched approval flow

Some findings require a design judgment call that an LLM shouldn't make unilaterally. These include:

• Focus order changes that affect perceived reading flow
• Nested-interactive component restructuring
• Fixed-width layouts that need responsive redesign

For these, the agent proposes a fix as a unified diff but does not apply it. All proposals are collected into PROPOSAL.md at your repo root. You review them once in batch, annotate each with APPROVE or REJECT, and the agent applies all approved diffs on a follow-up pass.

# PROPOSAL.md — generated by wcag-audit fix pass
## [PROPOSAL] rc-def456 — focus-order in <NavMenu>
Reason: Tab order follows DOM order but visual order differs. Requires design input.

--- a/src/components/nav-menu.tsx
+++ b/src/components/nav-menu.tsx
@@ -12,6 +12,7 @@
-  <ul className="nav-list">
+  <ul className="nav-list" style={{ display: "flex", flexDirection: "column" }}>
     {items.map(...)}
   </ul>

Decision: APPROVE  ← fill in APPROVE or REJECT

Convergence expectations

How many iterations you'll need depends on whether the Next.js plugin is installed.

The 5–10% of findings that persist after iteration are usually audit pessimism (the rule fires but the element is genuinely accessible) or AI-vision variance (screenshot rendering differs from real user experience). Use wcag-audit dismiss to mark these with a reason — they won't reappear in future scans.

A worked example

Here's what a typical project looks like across iterations. Starting point: a mid-sized Next.js SaaS app, 47 routes, no prior a11y work.

Before: 180 findings (23 critical, 44 serious, 113 moderate)
Codemods fired: 108 auto-fixes applied at scan time
LLM fixed: 60 findings across 18 source files
Verify passed: 168/168 applied fixes confirmed
Remaining: 12 findings
→ Re-scan to continue

Before: 12 findings (0 critical, 2 serious, 10 moderate)
LLM fixed: 9 findings
Dismiss (false positive): 1 finding dismissed with reason
Needs-design proposals: 2 findings → PROPOSAL.md
Remaining: 0 actionable
→ Done. Review PROPOSAL.md at your convenience.

Total time: approximately 25 minutes including two scan runs. The 2 design proposals in PROPOSAL.md can be reviewed and approved in a follow-up pass whenever the design work is ready.

Glossary