Getting started

Your first repair

This walkthrough uses a checkout test whose button's test id changed. Your output will differ, but every session follows the same shape.

Analyze

$ npx playwright test
  1 failed
    [chromium] › tests/checkout.spec.ts:18:5 › applies a discount code
$ npx kwikqa analyze
Diagnosis request -> the KwikQA service, which forwards it to OpenRouter
  Model:     anthropic/claude-haiku-5.5 via anthropic, effort max
  Evidence:  12 redacted items from report, trace, source
             2 redactions applied, 1 item withheld by policy
  Estimate:  at most 18,400 input + 64,000 output tokens, at most $0.34
  Caps:      $2.00 per request
  Payload:   4f9c2a7e1b0d83c5... (exactly this redacted payload is sent)
Send this request?

Nothing has been sent yet. The preview tells you where the request goes, which model answers it, how much evidence it carries, what was redacted or withheld, and the most it can cost. The payload hash binds your approval to exactly this packet. Answer n and nothing is sent or counted.

#1 The spec waits for test id "apply-coupon"; the trace shows the button is now
   data-testid="apply-discount", role button "Apply discount".
   owner: test-support, evidence: strong, cause: locator-drift
  Next: Update the locator in tests/checkout.spec.ts to the button's role and name.

Result: diagnosed (test-support-owned)
Run `npx kwikqa fix` to propose a repair.
Record: .kwikqa/runs/run_8c1d.../records/rec_41a2....json

Causes are ranked. owner says whose fault the evidence points to, and only test-support causes can be repaired. evidence is a grade, not a percentage: strong, moderate, weak, or insufficient. The record is the full result on disk.

Fix

$ npx kwikqa fix
Repair proposal request -> the KwikQA service, which forwards it to OpenRouter
  Model:     openai/gpt-6-luna via openai, effort max
  ...
Send this request? y

Proposed repair
  Intent:    Apply a discount code through the cart's discount button.
  Preserves: The test still asserts the discounted total of $9.00.
  Changes:   1 file, 2 lines

--- a/tests/checkout.spec.ts
+++ b/tests/checkout.spec.ts
-  await page.getByTestId("apply-coupon").click();
+  await page.getByRole("button", { name: "Apply discount" }).click();

Validation commands (run later by `kwikqa validate`):
  cli.js test tests/checkout.spec.ts:18 --project=chromium ...
Apply this patch?

fix reuses the diagnosis from analyze for the same run, so it doesn't count another analysis. The repair request is separate and counts as one fix. The proposal has already passed the repair rules; what you approve here is the exact diff and the exact commands validate will run.

Result: awaiting-validation (patch-applied)
Run `npx kwikqa validate` to verify the patch.

Validate

$ npx kwikqa validate
Result: repaired (validation-passed)

The patch stays in your working tree, uncommitted, for you to review and commit. If validation had failed, KwikQA would roll the patch back and offer one retry:

Result: repair-failed (validation-failed)
Run `npx kwikqa fix --retry` to re-diagnose from the validation evidence (one retry left).

The retry re-diagnoses from the new evidence and proposes one revised patch, with fresh previews and approvals. It is free. If the revised patch also fails, KwikQA rolls it back and stops.