@ia-qa/self-healing 1.6.1 → 1.6.3

package/skills/ia-qa-heal/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ia-qa-heal
+description: >-
+  Repair, audit and reason about E2E test locators (Playwright, Cypress, Selenium) by
+  reading a local page contract instead of opening a browser. Use when a UI test fails on
+  a locator (selector not found, strict-mode violation, a renamed button or label), when
+  tests must be updated after a UI change, when asked which pages a suite covers, or
+  whether a suite still names elements that exist. Requires @ia-qa/self-healing
+  (`ia-qa-heal`). Runs entirely on the user's machine.
+---
+
+# ia-qa-heal — heal locators from the contract, not from a browser
+
+## 1. Read the contract before you open anything
+
+`.ia-qa/mapping/<page>.json` is a captured snapshot of every interactive element on a page:
+
+```json
+{
+  "page": "checkout", "url": "/checkout", "capturedAt": "2026-08-02T17:40:20.067Z",
+  "elements": [
+    { "role": "button", "name": "Pay now", "selector": "#root form > button", "context": "main" },
+    { "role": "link", "name": "Back to cart", "selector": "a[href=\"/cart\"]", "context": "nav", "href": "/cart" }
+  ]
+}
+```
+
+A failing locator is usually answered by **reading that file**: the element's current role, its
+accessible name, a selector that works. A test asserting a `button` where the page now renders a
+`link` is one `grep` away — no browser, no screenshot, no round-trip. Do this first.
+
+Where things live:
+
+| Path | What it is |
+|---|---|
+| `.ia-qa/mapping/` | the current capture |
+| `.ia-qa/baseline/` | the committed reference `diff` compares against |
+| `.ia-qa/mapping/_layouts/` | elements shared by every page (navbar, footer) — one fix, not N |
+| `.ia-qa/usage.json` | the locators the suite actually uses (produced by `ingest`) |
+| `.ia-qa/mapping/_overview.md`, `_navigation.md`/`.svg` | app index + navigation graph |
+
+Open a browser only when the contract *cannot* answer: the page is not mapped, or the element
+exists only in a state nothing captured (behind a tab, a modal, a mode toggle).
+
+## 2. Which verb answers which question
+
+| The user's question | Verb |
+|---|---|
+| "my tests broke — fix them" | `run` (capture during their suite → diff → confirm → fix → re-run to verify) |
+| "did anything drift?" | `diff` → PASS/FIX/BLOCK (the CI gate) |
+| "day one, no baseline — is my suite still valid?" | `audit` |
+| "is the app I mapped even sound?" | `check` (dead links · unnamed elements · name collisions · orphan pages) |
+| "which pages am I *not* covering?" | `discover` (`--sitemap` / `--crawl`; suggests only) |
+| "give me the app's structure" | `graph --format mermaid\|svg\|json\|markdown` |
+| "apply the rewrites" | `fix` — `--dry-run` first, always |
+| "what do my tests actually use?" | `ingest` |
+| first-time setup | write `.ia-qa/config.json` directly — `init` is a TTY wizard and **will refuse in your shell** |
+
+Exact flags: `ia-qa-heal <verb> --help`. Do not guess them from this file.
+
+## 3. Reading a verdict
+
+- **PASS** — nothing moved.
+- **FIX** — every drifted element was re-identified; `fix` rewrites them deterministically.
+- **BLOCK** — a human decides.
+
+Row statuses: `ok`, `renamed`, `healable`, `ambiguous`, `lost`, `added`. Any row may also carry
+`rebound: true` + `reboundTo`.
+
+BLOCK is raised by `lost` (element gone), `ambiguous` (several candidates — a coin flip), `rebound`
+(the old selector still resolves, but onto a **different** element: the test stays green while
+clicking the wrong thing), or a name-drift finding that is not attributable.
+
+## 4. Never do this
+
+1. **Never hand-rewrite a locator reported `unattributable`.** `getByText`, `cy.contains`,
+   `getByTitle`, `getByAltText` name a **string, not an element** — nothing proves the test meant
+   the renamed button rather than a heading that never moved. They are reported with `file:line`
+   and hold the verdict at BLOCK *on purpose*. Editing one breaks a test that was **passing** —
+   the only outcome worse than the drift. Surface it to the human instead.
+2. **Never treat `audit` as a gate.** It is advisory (exit 0) unless `--strict`: a "missing"
+   locator may live on an unmapped page, or an unmapped *state*.
+3. **Never call a green `run` a green app.** `run` only re-captures the pages the suite actually
+   exercised; the rest keep the baseline's `capturedAt`, are `stale`, and sit outside the verdict.
+   Read the coverage line it prints before concluding anything.
+4. **Never diff a `map` baseline against a `run` capture.** The two read a page differently and
+   produce phantom drift. The tool warns — take the warning, don't explain it away.
+5. **Never run `fix` blind.** `--dry-run` first, show the plan, then apply. It never commits;
+   neither should you without the human seeing the diff.
+6. **There is no `--ai` flag on `ia-qa-heal`,** and adding one is not the fix — the gate stays
+   deterministic by design. The BYOK layer is the separate `ia-qa-heal-ai` binary: it *suggests*
+   matches for `lost`/`ambiguous` rows for a human to confirm, and never gates CI.
+7. **Renames need an inventory.** `diff` can only gate on a changed *label* if `ingest` has
+   inventoried what the suite uses. No `usage.json` ⇒ no name escalation — so if their tests
+   locate by `getByRole(..., { name })`, run `ingest` before trusting a PASS.
+
+## 5. What leaves the machine
+
+Nothing, except: requests to the user's **own** `baseUrl` (`check`'s link half, `discover --crawl`
+— GET only, same origin, never a `/logout` or `/delete` URL), and `ia-qa-heal-ai` calling the
+user's own LLM if they opted in. Say that plainly rather than implying more or less.