How it works

The workflow

KwikQA is a fixed pipeline with a clear stop at every step. Each command ends in one outcome and one reason code, written to a record in .kwikqa/runs/.

1. Read the run

KwikQA reads Playwright's JSON report and, when they exist, the trace and attachments of each failed test. It checks that the run is complete: an interrupted run, a report with errors, or a run with no failures stops here with a reason code instead of a guess. Failures that share a symptom are grouped, so one root cause isn't diagnosed twice.

2. Build the evidence packet

From the report, traces, and short excerpts of the test source around the failure, KwikQA builds a bounded evidence packet on your machine. Secrets and sensitive fields are redacted, items the policy doesn't allow are withheld, and images are described by size only. Every redaction and omission is counted in the preview.

3. Ask, once, with your approval

The preview shows the destination, model, evidence, cost estimate, caps, and a hash of the exact payload. Approving sends one request with that payload; the request has a fixed output cap and a dollar cap. Nothing is retried behind your back.

4. Grade the diagnosis

The answer is checked against the evidence before you see it. Each cause must cite evidence that exists in the packet. It gets an evidence grade (strong, moderate, weak, or insufficient) and a probable owner (test-support, application, environment, or undetermined). Confidence alone never authorizes a repair: a repair needs positive, cited evidence that the fault is in test code.

5. Propose a repair

fix sends a separate repair request. The model must say what the test intends, what behavior the repair preserves, and which evidence each edit relies on. KwikQA resolves every edit against your files locally and checks the result against the repair rules. A proposal that breaks a rule is rejected with its reasons and never shown as a patch.

6. Apply with a journal

You approve the exact diff and the exact validation commands. KwikQA writes a journal before it touches a file, then applies the patch. Files with your own uncommitted changes are never edited.

7. Validate or roll back

validate runs the original test, and the tests the change could affect, in fresh processes, writing new artifacts without touching the original evidence. A pass of every required check is repaired. A failure, or any check that is skipped, interrupted, stale, or incomplete, rolls the patch back. Rollback restores exactly the bytes KwikQA changed and stops with rollback-conflicted rather than overwrite edits you made afterwards.

8. One retry, then stop

After a failed validation, fix --retry rebuilds the evidence from the validation run and asks for one revised patch, with fresh approvals. If that fails too, KwikQA rolls it back and stops. It never loosens its rules or loops until the build is green.