@xera-ai/skills 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/skills",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "files": [
     "*.md",
     "version.json"

package/version.json

@@ -1,6 +1,6 @@
 {
-  "skills": "0.4.0",
-  "compatible_prompts": "^2.2.0",
+  "skills": "0.4.2",
+  "compatible_prompts": "^2.3.0",
   "skill_files": [
     "xera-run.md",
     "xera-fetch.md",
@@ -8,6 +8,7 @@
     "xera-script.md",
     "xera-exec.md",
     "xera-report.md",
-    "xera-promote.md"
+    "xera-promote.md",
+    "xera-impact.md"
   ]
 }

package/xera-impact.md

@@ -0,0 +1,82 @@
+---
+name: xera-impact
+description: Pre-flight impact analysis. Given a ticket, identify scenarios that may be affected by its changes (graph-walk via project knowledge graph), then optionally re-run them. Use before merging or when AC has just changed for a ticket. Available v0.6.2+.
+---
+
+The user invoked `/xera-impact <TICKET> [--depth 1|2|3] [--min-priority p0|p1|p2]`. If no key, ask.
+
+This skill walks the project knowledge graph (`.xera/graph/`) to find scenarios that depend on the modified areas of `<TICKET>`. It does NOT re-fetch or re-script — it's strictly a query + optional re-execution.
+
+## Step 1 — Verify graph snapshot is fresh
+
+Run:
+
+```bash
+bun run xera:graph-snapshot --check
+```
+
+If stale, the subcommand auto-rebuilds. If `<TICKET>` is not in the graph, this step will succeed but Step 2 will exit with code 2 — that means you must run `/xera-fetch {{TICKET}}` first.
+
+## Step 2 — Compute impact
+
+Run:
+
+```bash
+bun run xera:impact-prepare {{TICKET}} [--depth N] [--min-priority P]
+```
+
+Pass through any flags the user provided. On exit code 2, surface: *"Ticket {{TICKET}} not in graph — run `/xera-fetch {{TICKET}}` first"* and STOP.
+
+The subcommand writes:
+- `.xera/impact/{{TICKET}}.json` (machine-readable)
+- `.xera/impact/{{TICKET}}.md` (human-readable)
+
+## Step 3 — Display summary
+
+Read `.xera/impact/{{TICKET}}.json`. If `scenarios.length === 0`, show:
+
+```
+Impact analysis for {{TICKET}} → no prior scenarios in modified areas
+(this is normal for new feature areas; nothing to re-run)
+```
+
+And STOP.
+
+Otherwise, count scenarios in 3 score buckets (high ≥7.0, medium ≥4.0, low <4.0). Display:
+
+```
+Impact analysis for {{TICKET}}  →  .xera/impact/{{TICKET}}.md
+
+N scenarios impacted (H high · M medium · L low)
+
+Top 3:
+  <ticketId> / "<name>"   [Pn]   <score>   <edge-summary>
+  ...
+```
+
+## Step 4 — Prompt re-run
+
+Ask the user: `Re-run impacted scenarios?  [Y]es / [p] P0 only / [s]elect / [n]o`
+
+- **[n]:** STOP. The user can inspect `.xera/impact/{{TICKET}}.md` separately.
+
+- **[Y]:** Group impacted scenarios by their owner ticket (`scenario.ticketId`). For each owner ticket, invoke `bun run xera:exec <owner-ticket>` (the existing exec subcommand). Collect the `RUN_ID` from each. Note: this re-runs the ENTIRE spec for each impacted owner, not just the impacted scenarios — Playwright doesn't natively support per-test selection from a json list without test-name regex. Acceptable for v0.6.2; precise per-scenario selection is a v0.6.x patch.
+
+- **[p]:** Filter `scenarios` array to `priority === 'p0'` only, then proceed as [Y].
+
+- **[s]:** Show numbered list with checkboxes; let the user pick. Then proceed as [Y] with the selected subset.
+
+## Step 5 — Recommend follow-up
+
+After exec runs complete, recommend:
+
+```
+{{N}} owner tickets re-run. Run `/xera-report {{TICKET}}` next to classify failures
+(TEST_OUTDATED detection will flag failures caused by THIS ticket's AC change).
+```
+
+## Edge cases
+
+- If `xera:impact-prepare` exits non-zero for any reason other than 2 (e.g. graph corrupted), surface the stderr and STOP.
+- If a re-run via `xera:exec` fails non-recoverably, continue with remaining tickets but note the failure in the final summary.
+- Respect `xera.config.run.autoImpact.enabled = false` — skip this skill if invoked recursively from `/xera-run` and config disables it.

package/xera-report.md

@@ -50,8 +50,38 @@ Step 4 below is *cognitive work that YOU, the session, must do*. It is not a she
 
    **Do not skip this step.** If you find yourself about to call `bun run xera:report` without having written this file, stop and write the file first.
 
+## Step 4b — TEST_OUTDATED pre-check (v0.6.1)
+
+For every scenario in `classifier-input.json` whose `outcome === "FAIL"`:
+
+1. Compute `scenarioId = sha1(<TICKET> + ":" + normalize(scenario.name))` (lowercase, single-spaced).
+2. Query the graph: `bun run xera:graph-query --ticket <TICKET> --format json | jq '.edges[] | select(.kind == "modifies") | select(.discoveredAt > <scenario.generatedAt>)'`.
+3. If there are 0 candidates → skip this scenario, no LLM call needed.
+4. If there are ≥1 candidates → run the `classify-outdated.md` prompt (located at `packages/prompts/classify-outdated.md`):
+   - Inputs: scenario gherkin + original AC, candidate tickets' AC, failure expected/actual from trace.
+   - Wrap untrusted ticket text using the v0.3 untrusted-input preamble pattern (boundary tags + refusal label).
+   - Output: JSON `{ classification, confidence, evidence }` per the prompt schema.
+5. Aggregate all decisions into `.xera/<TICKET>/runs/<RUN_ID>/outdated-decisions.json` keyed by `scenarioId`.
+
+**If lazy similarity is needed** (a candidate ticket exists but has no `similar` edges and is hot for many scenarios), first run:
+
+```bash
+bun run xera:graph-enrich --ticket <CANDIDATE>
+```
+
+This populates `similar` edges so future graph queries are richer. Skip if not needed.
+
 4a. **Heal sub-flow (only if SELECTOR_DRIFT present).** If the user passed `--no-heal` in the invocation, skip this entire sub-flow and proceed directly to step 5.
 
+**v0.6.1 update:** Before invoking heal, check whether the scenario's failure was classified as TEST_OUTDATED. Read `.xera/{{TICKET}}/runs/{{RUN_ID}}/outdated-decisions.json` (written at step 4b, available in the current session). If the scenario's entry has `classification === 'TEST_OUTDATED'` and `confidence >= 0.7`, **SKIP heal** and instead instruct the user to regenerate the scenario from the candidate ticket's new AC:
+
+```bash
+# Example:
+bun run xera:script <ORIGINAL_TICKET> --refresh-from <CANDIDATE_TICKET>
+```
+
+Heal is for selector drift (DOM moved); TEST_OUTDATED requires a scenario rewrite, not a heal.
+
 Otherwise: read `.xera/{{TICKET}}/classifier-input.json` (which you just wrote in step 4) and check whether any scenario has `class: "SELECTOR_DRIFT"`. If none, skip this entire sub-flow and proceed directly to step 5 (Aggregate + draft).
 
 If at least one scenario is SELECTOR_DRIFT, take the FIRST such scenario (by array order — the single-heal guard) and execute Phases A–C below. Subsequent SELECTOR_DRIFT scenarios are NOT auto-healed in the same `/xera-report` invocation; list them in the report output as "additional drifts: re-run /xera-report after applying the first heal."
@@ -118,8 +148,13 @@ If at least one scenario is SELECTOR_DRIFT, take the FIRST such scenario (by arr
 
 After the heal sub-flow finishes (whether it applied, refused, or errored), continue to step 5 below to aggregate + draft the report. The Jira comment in step 5 reflects the run as it was originally classified — heal results are a separate concern not (in v0.5) folded into the Jira comment.
 
-5. **Aggregate + draft.** Run: `bun run xera:report {{TICKET}} -- --input=.xera/{{TICKET}}/classifier-input.json`
-   This CLI: aggregates per-scenario classifications into an overall verdict, updates `status.json` with history, and writes `jira-comment.draft.md`. If exit code is non-zero, surface the error to the user; do not proceed to post.
+5. **Aggregate + draft.** Now invoke the existing `xera:report` flow as before:
+
+   ```bash
+   bun run xera:report {{TICKET}} --input=.xera/{{TICKET}}/classifier-input.json
+   ```
+
+   The `xera:report` subcommand reads `outdated-decisions.json` (if present) and may upgrade scenario classifications to `TEST_OUTDATED`. It aggregates per-scenario classifications into an overall verdict, updates `status.json` with history, and writes `jira-comment.draft.md`. If exit code is non-zero, surface the error to the user; do not proceed to post.
 
 6. **Show the draft.** Read `.xera/{{TICKET}}/jira-comment.draft.md`. Display its content to the user verbatim. Ask: "Post to Jira? (Y/n)" (default: Y, unless `meta.json.source === "local"` for SAMPLE tickets — then never post).
 
@@ -136,3 +171,54 @@ bun run xera:graph-record classify <TICKET> --run-id <RUN_ID>
 ```
 
 Non-fatal. Note: TEST_OUTDATED detection ships in v0.6.1 — for v0.6.0 this just emits `run.classified` events with existing 4-bucket classifications.
+
+## Step 10 — Notify ticket owner when TEST_OUTDATED detected (v0.6.1)
+
+For every scenario classified as `TEST_OUTDATED` in `outdated-decisions.json`, find the **original ticket** that owns the scenario (from graph: `xera:graph-query --ticket <SCENARIO_OWNER_TICKET> --format json`). Then post a Jira sub-task on that ticket via the existing Jira backend (the same code path `/xera-fetch` uses to read tickets — re-use the configured backend per `xera.config.ts.jira`):
+
+Body template:
+
+```
+Test for this ticket may be outdated due to changes introduced by <CURRENT_TICKET>. Confidence: <conf>. Run `xera:script <ORIGINAL_TICKET> --refresh-from <CURRENT_TICKET>` to regenerate the test from the new AC.
+```
+
+Tag the original ticket's assignee. This routes the signal to the right person, not the current QA running this report.
+
+In the current QA's session, only show a summary line:
+```
+3 impact tickets notified (ABC-100, ABC-145, ABC-178). No action required from you.
+```
+
+**Config:** Respects `xera.config.report.testOutdatedNotify`:
+- `'jira-subtask'` (default) — post sub-task as above
+- `'comment'` — post comment instead
+- `'console-only'` — only print to terminal, no Jira write
+
+## Step 11 — Dispute capture (v0.6.1, optional)
+
+After classification is displayed to the user, if any scenario has classification `TEST_OUTDATED` or `REAL_BUG`, prompt the user:
+
+```
+Agree with classifications above? [Y]es / [d]ispute
+```
+
+If the user picks `d`, prompt:
+```
+Which scenario? [N]
+What classification do you think it should be? (REAL_BUG / TEST_BUG / SELECTOR_DRIFT / FLAKY / TEST_OUTDATED)
+Reason (optional, single line):
+```
+
+Then emit a dispute event:
+
+```bash
+bun run xera:graph-record dispute \
+  --run-id <RUN_ID> \
+  --scenario-id <SCENARIO_ID> \
+  --from <ORIGINAL_CLASSIFICATION> \
+  --to <DISPUTED_CLASSIFICATION> \
+  --actor "$(git config user.email)" \
+  --reason "<REASON>"
+```
+
+Non-fatal: if it fails, log warning and continue. Dispute events are captured for v0.7+ classifier learning; v0.6.1 does not change classifier behavior based on disputes.

package/xera-run.md

@@ -18,6 +18,35 @@ Follow the same instructions as `xera-fetch.md`, but never prompt the user about
 
 If meta is missing or story_hash is older, refresh.
 
+## Step 1.5 — Auto-trigger impact analysis (v0.6.2)
+
+After `/xera-fetch` completes, check whether this ticket modifies areas that other tests depend on.
+
+Read `xera.config.run.autoImpact` (defaults: `{ enabled: true, threshold: 6.0 }`). If `enabled === false`, SKIP this step.
+
+Run:
+
+```bash
+bun run xera:impact-prepare {{TICKET}} --quiet
+```
+
+This writes `.xera/impact/{{TICKET}}.json` (no markdown). Exit code 2 means the ticket is not yet in graph — surface a warning and proceed (graph data only accumulates over time).
+
+Read the JSON. Count scenarios with `riskScore >= autoImpact.threshold`. If 0, no prompt — continue silently to Step 2.
+
+If ≥1 high-risk scenario, prompt the user:
+
+```
+{{N}} high-risk impacted scenarios detected for {{TICKET}}.
+Re-run them before generating the new script? [Y/n/details]
+```
+
+- **[Y]:** Iterate `bun run xera:exec <owner-ticket>` for each unique owner ticket. After each, check status; if all pass, continue to Step 2. If any fail, surface the failure and STOP — the user should diagnose existing-test breakage before introducing more changes.
+- **[n]:** Continue to Step 2.
+- **[details]:** Suggest the user run `/xera-impact {{TICKET}}` interactively for full details, then ask again.
+
+Non-fatal: if `xera:impact-prepare` itself exits abnormally, log the warning but continue to Step 2 — graph features are advisory, not gating.
+
 ## Step 2 — Feature
 
 Follow `xera-feature.md`. If `feature_generated_from_story_hash !== story_hash`, regenerate. If unchanged AND spec.ts exists, skip feature generation entirely.