qa-heal

qa-heal

Tests rot: selectors drift, labels change, waits get flaky — and a red suite that's just stale gets ignored, which is how real regressions slip through. qa-heal keeps the suite honest. For each failing test it decides why it fails and acts:

suite red  →  per failing test, in an isolated worktree:
   ├─ behaviour still holds, selector/label/timing drifted   → REPAIR the test (the HOW)  → green
   ├─ behaviour is gone / assertion no longer matches the app → REAL REGRESSION → leave red → file a bug
   └─ passes on retry                                         → stabilize (proper wait, no assertion change)
repairs  →  one branch + one MR ("qa-heal: repair N stale tests")  →  you review & merge
verify   →  an INDEPENDENT agent confirms the diff touched ONLY selectors/waits — no assertion moved
regressions → filed as issues (via the report step) → they flow into /qa-fix

🔒 The cardinal rule

Heal the HOW (selectors, locators, waits, setup) — never the WHAT (assertions). If a test can only go green by changing what it asserts, the test is right and the app changed: that's a real regression, not a stale selector. Weakening an assertion to force green would hide a real bug — qa-heal refuses to do it, and the independent Verify-heal pass exists specifically to catch any repair that touched an assertion.

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

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

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

Prerequisites

• The same qa.config.json qa-explore/qa-fix use (baseUrl, login, e2eDir, framework, and — to open the MR + file regressions — a tracker block + its token env var). Optional heal block: verify (default true), maxHeal, suiteCommand.
• Run from inside the target project's git repo — the healer works in a worktree and pushes a branch. Without a tracker it just leaves a local branch + diff for you.