@ia-qa/self-healing 1.7.7 → 1.7.10

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

@@ -52,6 +52,7 @@ exists only in a state nothing captured (behind a tab, a modal, a mode toggle).
 | "did anything drift?" | `diff` → PASS/FIX/BLOCK (the CI gate) |
 | "the suite already ran with `IAQA_CAPTURE=1`" | `diff` — **on its own**. It picks up `.capture/` and never opens a browser. Do *not* re-run `run`, and never `map` (that re-captures from scratch, without the session the suite had) |
 | "their suite takes 20 min and `run` runs it twice" | `run --no-verify` — the second run is the post-fix verification, and it is optional. Say what they lose: the exit code then reflects the diff, not a re-proved green suite |
+| "here is my failing test / red build — why?" | `explain --junit <file>` (or `--message "<error text>"`, or pipe the log). Start here when the user hands you a failure rather than a question: it names the locator, judges it against the two captures, and a **PASS rules drift out** so you stop hunting selectors. It re-runs nothing and edits nothing |
 | "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). Behind a login `--sitemap` sees nothing — `--crawl` is the one that works, and it reuses the session |
@@ -69,7 +70,7 @@ Exact flags: `ia-qa-heal <verb> --help`. Do not guess them from this file.
 
 ### Machine-readable outputs
 
-`diff`, `run`, `audit`, `check` and `history` all take `--json`. Prefer it over parsing prose.
+`diff`, `run`, `audit`, `check`, `explain` and `history` all take `--json`. Prefer it over parsing prose.
 Under `run --json`, every human line moves to stderr so stdout stays one parseable document.
 `diff --junit` / `run --junit` additionally write JUnit XML — the format a CI already knows.
 
@@ -158,6 +159,14 @@ clicking the wrong thing), or a name-drift finding that is not attributable.
    (`repairable` / `working` / `ambiguous` / `not seen`), and it is only meaningful next to
    the page coverage: `not seen` over 6 mapped pages out of 163 says nothing about the suite.
 
+15. **Never report `explain`'s PASS as "the test passes".** It says one thing: the locators in
+   that failure still reach their elements, so the red build is **not** selector drift. It
+   re-ran nothing, so it is not evidence of flakiness either — it *narrows* the search to
+   timing, test data or an application error. Tell the user which of those to look at next;
+   do not close the ticket. And never report its **refusal** as a pass: "cannot tell which
+   locator this is about" (exit 2) is an unanswered question, usually an un-ingested file
+   or a locator built at runtime, and the remedy is in the message.
+
 ## 5. What leaves the machine
 
 Nothing, except: requests to the user's **own** `baseUrl` (`check`'s link half, `discover --crawl`