qa-fix

The fixing half of the closed loop. qa-explore files issues for what it finds; a human marks the real ones with the fix label; qa-fix turns those labelled issues into reviewed merge requests.

qa-explore  →  files issue per confirmed finding
human       →  adds the fix label to the genuine bugs        ← the triage gate
qa-fix Fix  →  per labelled issue, in an isolated worktree:
               reproduce → write RED regression test (run against the CHANGED code) → fix
               → test GREEN + suite green → push branch → open MR ("Closes #iid")
qa-fix Verify → an INDEPENDENT skeptic checks out the branch: audits the test, confirms
               red-without-fix / green-with-fix, reproduces the bug is gone, reviews the diff
               → comments its verdict on the MR (qa::fix-verified | qa::fix-doubt)
human       →  reviews & merges the MR                        ← the merge gate

Two human gates, both lightweight, both in the tracker: which bugs get fixed (the label) and what actually ships (the merge). qa-fix never merges and never touches an unlabelled issue. The fix is checked twice: deterministically (its own regression test + suite) and by an independent agent (the Verify-fix pass) — the same adversarial idea as explore→verify, now for fixes.

Engine (invoke via the Workflow tool; do not inline)

• ${CLAUDE_PLUGIN_ROOT}/skills/qa-fix/engine/qa-fix.workflow.js

(If $CLAUDE_PLUGIN_ROOT is unset, the skill is at ~/.claude/skills/qa-fix — resolve the engine path relative to this SKILL.md.)

Prerequisites

• A qa.config.json with a tracker block (type = gitlab | github, host, project, tokenEnv, fixLabel, fixingLabel, defaultBranch) and a fix block. Same file qa-explore uses.
• The token: a Personal Access Token with api scope (GitLab) exported in the env var named by tracker.tokenEnv (e.g. GITLAB_TOKEN). Confirm it is set before running — never inline or echo it.
• Run this skill from inside the target project's git repo — each agent works in a git worktree of the current repo, and pushes a branch to its origin. Push access (SSH/PAT) must already work.
• fix.buildTest (a code-level test command) and/or fix.localRun (how to build + serve the fixed app locally) so the regression test runs against the changed code, not the stale live app. Without either, the agent falls back to building/serving from the worktree itself — slower and less reliable. See the Notes.

How to run

1. Resolve config. Load qa.config.json (cwd or its E2E dir). Read the tracker block. If tracker.type is none/missing, stop and tell the user to configure the tracker first (point at qa.config.example.jsonc).
2. Confirm the token is present ([ -n "$GITLAB_TOKEN" ] or the configured env var) without printing it. If absent, ask the user to export it and stop.
3. Confirm scope with the user before any push. Pushing branches and opening MRs is an outward action. State how many issues carry the fix label and that running will open that many MRs against defaultBranch. Proceed only on an explicit go-ahead (this run is the per-operation push authorization). Pass maxFixes if the user wants to cap a first run.
4. Run the engine. Workflow({ scriptPath: "<engine>/qa-fix.workflow.js", args: { ...config } }). It:
   • Select: lists open issues with fixLabel, skipping any already tagged fixingLabel or already linked to an MR.
   • Fix (one isolated-worktree agent per issue): claims the issue (adds fixingLabel + a comment), understands the bug, writes a red regression test that asserts the correct behaviour and runs against the changed code (code-level preferred; E2E only against a local build of the worktree — never baseUrl, which serves the old code), fixes until green, runs the broader checks/suite, pushes qa-fix/<iid>-<slug>, opens an MR (Closes #<iid>), comments the link on the issue. Not safely auto-fixable → no bad MR: it comments why, drops fixingLabel, returns skipped-unfixable.
   • Verify-fix (independent skeptic, own worktree; skip with fix.verify: false): checks out the MR branch and re-verifies — test honesty, that it is red without the production change and green with it, that the original repro is gone, and the diff has no obvious side-effects. Posts a ✅/⚠️ verdict comment and labels the MR qa::fix-verified or qa::fix-doubt.
5. Report back. Summarize per issue: MR opened (link + regression test + the verify verdict), skipped-as-unfixable (with reasoning), or failed. Flag any MR that came back fix-doubt so the human looks harder. Remind the user the MRs are theirs to review and merge.

Branch strategy

• per-issue (default, recommended): one branch + one MR per bug. Atomic and independently reviewable — you merge the good ones and reject the bad ones separately, and each MR carries exactly the regression test for its bug. This is not an MR flood: volume is bounded by the human fixLabel gate (only labelled issues get fixed) plus maxFixes per run. Label 3 → get 3 MRs.
• batched: one branch + one MR for the whole run (separate commits per bug). Only for piles of small, related fixes where N tiny MRs would be more annoying to review than one. Set fix.fixStrategy: "batched".

Notes

• Tests run against the CHANGED code, never baseUrl. The live app serves the old deployed code until you redeploy, so it can't prove a fix. The regression test must execute against the worktree: a code-level unit/integration test (fix.buildTest) sees the fix directly and is preferred; an E2E test only proves anything when pointed at a local build of the worktree (fix.localRun). Both the fixer and the independent verifier enforce this.
• The regression test is the contract, checked twice. Its definition of done: red before the fix, green after, suite still green — and an independent agent re-confirms that (test honesty + red-without/green-with + bug-gone + diff review) before you see the MR. The MR carries both the proof and the second opinion, and the test joins Step 0 for the next qa-explore run.
• Never weaken a test to force green, never merge, never fix outside the labelled issue's scope. Smallest correct change, repo conventions, CLAUDE.md respected.
• Cadence: on demand for now (/qa-fix after triaging the tracker). A scheduled/CI variant is on the roadmap (Claude Agent SDK standalone runner).