@codyswann/lisa 2.187.4 → 2.188.1

package/plugins/src/base/skills/product-walkthrough/SKILL.md

@@ -1,88 +1,62 @@
 ---
 name: product-walkthrough
-description: "Methodology for evaluating the live product via a real browser (Playwright MCP) when planning work or evaluating a PRD. Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change — this skill grounds the analysis in what actually exists today. Invoke this skill from notion-to-tracker (Phase 2b live-product walkthrough), jira-create, and any PRD intake flow whose work touches existing user-facing surfaces."
+description: "Methodology for evaluating the live product when planning work or evaluating a PRD. Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change — this skill grounds the analysis in what actually exists today. Driving the product is owned by the `use-the-product` core (which detects the product type — DOM web, HTTP/API, canvas game, CLI, IaC — resolves the per-environment mutation policy from .lisa.config.json so production is never mutated by accident, and explores through the project's personas when defined); this skill adds the planning lens. Invoke from notion-to-tracker (Phase 2b live-product walkthrough), jira-create, and any PRD intake flow whose work touches existing user-facing surfaces."
 allowed-tools: ["Skill", "Bash", "Read", "mcp__plugin_playwright_playwright__browser_navigate", "mcp__plugin_playwright_playwright__browser_snapshot", "mcp__plugin_playwright_playwright__browser_take_screenshot", "mcp__plugin_playwright_playwright__browser_click", "mcp__plugin_playwright_playwright__browser_type", "mcp__plugin_playwright_playwright__browser_select_option", "mcp__plugin_playwright_playwright__browser_fill_form", "mcp__plugin_playwright_playwright__browser_press_key", "mcp__plugin_playwright_playwright__browser_hover", "mcp__plugin_playwright_playwright__browser_navigate_back", "mcp__plugin_playwright_playwright__browser_resize", "mcp__plugin_playwright_playwright__browser_tabs", "mcp__plugin_playwright_playwright__browser_console_messages", "mcp__plugin_playwright_playwright__browser_network_requests", "mcp__plugin_playwright_playwright__browser_wait_for", "mcp__plugin_playwright_playwright__browser_close"]
 ---
 
 # Live Product Walkthrough
 
-Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change. This skill defines how to use a real browser (via Playwright MCP) to evaluate the live product *before* planning tickets, so the work is grounded in what actually exists today.
+Reading a PRD or a mock without seeing the current product produces tickets that misjudge the change. This skill defines how to evaluate the live product *before* planning tickets, so the work is grounded in what actually exists today.
+
+**How you drive the product is owned by the `use-the-product` core skill** — it detects the product type (web / API / game / CLI / IaC), resolves the target environment and its **mutation policy** from `.lisa.config.json`, and discovers the project's **personas**. A walkthrough is read-leaning: prefer the policy's **read-only** actions, and only mutate when both the policy allows it (`full`) and a flow genuinely can't be understood without it. This skill adds the **planning lens** below.
 
 ## When to invoke
 
 Always run a walkthrough when the work touches user-facing surfaces:
 
 - The PRD describes a change to an existing screen, flow, or interaction
-- The PRD adds something *next to* existing functionality (entry points, navigation, related screens)
+- The PRD adds something *next to* existing functionality (entry points, navigation, related surfaces)
 - A mock or prototype implies a re-style or re-flow of something currently shipped
 - The change is a "bug" framed as a fix to current behavior — you must see the current behavior before reasoning about the fix
 
-Skip when the work is purely backend with no user-visible surface, type-only, doc-only, or affects a screen that does not yet exist in production / dev.
-
-## Configuration
-
-Required inputs (ask if not set):
-
-| Variable | Purpose | Example |
-|----------|---------|---------|
-| `E2E_BASE_URL` | Frontend base URL to walk through | `https://dev.example.io/` |
-| Sign-in account | Test user to sign in as for the affected flows | from PRD config / 1Password / env |
-| Sign-in credentials | How to obtain (1Password item, env vars) | `E2E_TEST_PHONE`, `E2E_TEST_OTP` |
-
-Walk through `dev` (or the env named in the PRD) — never `prod` for exploratory walkthroughs unless explicitly asked.
+Skip when the work is purely internal (type-only, doc-only) or affects a surface that does not yet exist in production / dev.
 
-## Process
+## 1. Plan the walkthrough
 
-### 1. Plan the walkthrough
+Before driving anything, list the surfaces the change will touch:
 
-Before opening the browser, list the surfaces the change will touch:
-
-- Which screens/routes are involved (current and new)?
+- Which screens/routes/endpoints are involved (current and new)?
 - Which user roles need to be exercised (admin / customer / etc.)?
 - Which states matter (signed-out, signed-in, empty, populated, error, loading)?
-- Which viewports matter (desktop always; mobile when responsive; tablet rarely)?
-
-Write this list down. If you can't, the PRD is too vague — note this as a coverage smell and surface it as an Open Question on the resulting ticket.
-
-### 2. Open the browser and sign in
+- For a DOM web app, which viewports matter (desktop always; mobile when responsive)?
 
-1. `browser_navigate` to `E2E_BASE_URL`.
-2. `browser_resize` to the primary viewport (default desktop 1512×768).
-3. Sign in via the test account. Use `browser_fill_form` and `browser_click`. Capture the post-login screen with `browser_snapshot` or `browser_take_screenshot`.
+Write this list down. If you can't, the PRD is too vague — note it as a coverage smell and surface it as an Open Question on the resulting ticket.
 
-### 3. Walk the affected surfaces
+## 2. Drive the current product
 
-For each surface from step 1:
+**Invoke `use-the-product`** to detect the type, resolve the environment + mutation policy, and discover personas — then drive the surfaces from step 1 through its per-type playbook (browser for DOM, `curl` for an API, canvas+input for a game, `cdk synth`/`diff` for IaC). Capture evidence as you go: for a DOM app, a `browser_snapshot` (accessibility tree — best for reasoning) and a `browser_take_screenshot` (visual) per surface and per state, plus `browser_console_messages` / `browser_network_requests` after interactions; for an API, representative request/response pairs; for a game, screenshots of each state. If the project defines personas, walk the surfaces as the relevant archetype(s).
 
-1. Navigate to it. Capture a `browser_snapshot` (accessibility tree — better for reasoning) and a `browser_take_screenshot` (visual evidence).
-2. Exercise the relevant interactions. Capture state transitions.
-3. Capture each state that matters (empty, populated, error, loading) — explicitly trigger them where possible.
-4. For responsive changes, `browser_resize` to the secondary viewport (mobile 375×812) and re-capture.
-5. `browser_console_messages` and `browser_network_requests` after each interaction — surface any errors, 4xx/5xx, or unexpected calls.
+Honor the mutation gate: on a `read-only` env, observe without submitting; never walk a `forbidden` env (production defaults to forbidden). Treat console errors, 4xx/5xx, and unexpected calls as findings.
 
-### 4. Record findings
+## 3. Record findings
 
 For every walkthrough, record:
 
-- **What exists today**: a short prose description of the current flow, the components in use (if you can identify them from the DOM via `browser_snapshot`), and the states observed.
-- **What the PRD changes**: explicit delta — added screens, removed screens, modified components, new states, removed states.
-- **Existing-component reuse candidates**: components in the current product that could absorb the new behavior. The PRD-vs-current-product comparison drives which existing components a developer should reuse instead of building new (see `lisa:tracker-source-artifacts` §7).
-- **Design-vs-current-product divergence**: places where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic "rebuild from scratch" — see `lisa:tracker-source-artifacts` §3 (mocks define visual intent, not implementation shortcut).
-- **Coverage smells**: states the PRD doesn't address that exist today (e.g., the mock shows the empty state but ignores the populated state that has 90% of users).
-- **Behavioral surprises**: anything that doesn't match the PRD's assumptions about current behavior — these are usually the most valuable findings, because they invalidate parts of the PRD.
+- **What exists today**: a short prose description of the current flow, the components/endpoints in use (identify them from the snapshot/routes where you can), and the states observed.
+- **What the PRD changes**: explicit delta — added / removed / modified surfaces, new/removed states.
+- **Existing-component reuse candidates**: components or endpoints in the current product that could absorb the new behavior (see `lisa:tracker-source-artifacts` §7).
+- **Design-vs-current-product divergence**: where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic rebuild (see `lisa:tracker-source-artifacts` §3).
+- **Coverage smells**: states the PRD doesn't address that exist today (e.g. the mock shows the empty state but ignores the populated state 90% of users see).
+- **Behavioral surprises**: anything that doesn't match the PRD's assumptions about current behavior — usually the most valuable findings, because they invalidate parts of the PRD.
 
-### 5. Attach evidence to the originating context
+## 4. Attach evidence and close
 
-Capture screenshots/snapshots in a way that the originating ticket / Notion comment / PRD review can reference them.
+Capture evidence so the originating ticket / Notion comment / PRD review can reference it. Close the session when done (`browser_close` for a browser) — walkthroughs are short, focused, and one-shot.
 
-- For **PRD intake**: include a "Current Product" comment on the Notion PRD with the findings prose and inline screenshots of the current state alongside each affected screen mentioned in the PRD.
-- For **ticket creation**: include the findings under `## Current Product` in the ticket description (Story or Epic). Reference the screenshots as remote links if hosted, or inline them as attachments.
+- For **PRD intake**: include a "Current Product" comment on the Notion PRD with the findings prose and inline screenshots alongside each affected surface.
+- For **ticket creation**: include the findings under `## Current Product` in the ticket description (Story or Epic). Reference screenshots as remote links or attachments.
 - For **change-impact analysis**: produce a short report; the consuming skill decides where it lands.
 
-### 6. Close the browser
-
-`browser_close` when done. Walkthroughs are short, focused, and one-shot — do not leave a session open across phases.
-
 ## Findings format
 
 Use this structure when emitting walkthrough findings, so consuming skills can splice them into tickets / comments unchanged. The `## Current Product` heading matches what `lisa:jira-write-ticket` Phase 4e expects to inherit — keep the heading exact.
@@ -90,15 +64,16 @@ Use this structure when emitting walkthrough findings, so consuming skills can s
 ```text
 ## Current Product
 
-**Environment**: <E2E_BASE_URL> as <account/role>
-**Viewports exercised**: Desktop 1512×768, Mobile 375×812
+**Environment**: <target> as <account/role> (<mutation level>)
+**Explored as**: <persona(s) or "generic representative user">
+**Viewports exercised**: Desktop 1512×768, Mobile 375×812   (DOM web only)
 
 ### Surfaces walked
-1. <route> — <one-line current behavior>
-2. <route> — <one-line current behavior>
+1. <route/endpoint/screen> — <one-line current behavior>
+2. <route/endpoint/screen> — <one-line current behavior>
 
 ### What exists today
-<2-4 sentence prose summary of the current flow and components in use>
+<2-4 sentence prose summary of the current flow and components/endpoints in use>
 
 ### Delta vs. PRD
 - ADDED: <new surface/state from PRD>
@@ -107,23 +82,23 @@ Use this structure when emitting walkthrough findings, so consuming skills can s
 - UNCHANGED-BUT-IMPACTED: <existing surface PRD doesn't mention but will be affected>
 
 ### Existing-component reuse candidates
-- <component or screen> — could absorb <new behavior>
+- <component / endpoint / screen> — could absorb <new behavior>
 
 ### Design-vs-current-product divergence
-- <mock or prototype reference> diverges from <current screen> in: <specific dimension>
+- <mock or prototype reference> diverges from <current surface> in: <specific dimension>
 - Recommendation: <reuse / new build / discussion>
 
 ### Coverage smells & behavioral surprises
 - <smell or surprise>
 
 ### Evidence
-- <list of screenshots/snapshots, with captions>
+- <list of screenshots/snapshots/request-response pairs, with captions>
 ```
 
 ## Rules
 
 - Walk before you write. If the work touches existing user-facing surfaces and the walkthrough wasn't done, the resulting ticket is missing context — don't ship it.
-- Never walk `prod` for exploratory analysis. `dev` (or the env named in the PRD) only.
+- Never walk a `forbidden` environment (production is forbidden by default). Use `dev`/`staging` per the `exploration` config, and default to read-only for a planning walkthrough.
 - Treat console errors and unexpected network calls as findings — they often reveal undocumented behavior the PRD assumes is fine.
 - Findings drive `## Open Questions` on tickets, not silent assumptions. If the current product contradicts the PRD, surface it as a BLOCKER.
-- This skill captures observations; it does not edit JIRA or the PRD. Consuming skills decide where findings land (ticket description, Notion comment, validator input).
+- This skill captures observations; it does not edit the tracker or the PRD. Consuming skills decide where findings land.

package/plugins/src/base/skills/use-the-product/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: use-the-product
+description: Shared methodology for actually USING a project's product the way its real end user would — across product types (DOM web app, HTTP/API backend, canvas game, CLI/library, IaC/CDK). Detects the product's consumer-facing interface, drives it as that consumer, gated by a per-environment mutation policy read from .lisa.config.json (so the agent never mutates production data by accident), and lensed through the project's personas/subagents when it defines them. Invoked by exploratory-qa (files defect/UX tickets) and product-walkthrough (grounds planning in the live product); rarely run standalone.
+---
+
+# Use the Product
+
+## The one idea
+
+Every product has a **consumer-facing interface**. To evaluate a product you (1) **detect** that interface, (2) **resolve where you're allowed to drive it and how much you may change**, and (3) **drive it as the real consumer would** — through the project's personas when it has them. This skill owns steps 1–4 below; the **caller** decides what to *do* with what you find (`exploratory-qa` files tickets, `product-walkthrough` grounds planning).
+
+Driving the product means **interacting** with it. Static route scans, HTTP fetches, screenshots-alone, and reading the code are *supporting evidence only* — never a substitute for actually using it.
+
+## 1. Detect the product type & interface
+
+Infer from the repo; if genuinely ambiguous, ask one concise question.
+
+| Signals | Type | Consumer-facing interface |
+|---|---|---|
+| `vite`/`next`/`angular`/`svelte` + `index.html`, DOM UI | **DOM web app** | the rendered UI in a real browser |
+| API server (`nest`/`express`/`fastify`/serverless handlers), OpenAPI, no frontend | **HTTP / API backend** | the API endpoints |
+| `phaser`/`pixi`/canvas game | **Canvas game** | the canvas + input (keyboard/pointer), read visually |
+| `cdk.json` / Terraform / IaC | **IaC / CDK** | the resources it provisions (+ synth output) |
+| `bin/` CLI or published library, no server | **CLI / library** | the commands / public API |
+
+## 2. Resolve the environment & mutation policy — the gate
+
+Read the `exploration` block from `.lisa.config.json` (a repo-local config overrides a global one):
+
+```jsonc
+"exploration": {
+  "default": "<env-name>",              // which env to use when none is passed
+  "environments": {
+    "<name>": {
+      "url": "https://dev.example.io",  // web/API target (omit for local CLI/game)
+      "provision": true,                // IaC/ephemeral: stand up, then tear down
+      "mutation": "forbidden | read-only | full",
+      "identity": "<test-account ref>", // which login to use (env var / 1Password ref)
+      "prodMutationAck": "<one sentence>" // REQUIRED to allow `full` on a production-named env
+    }
+  }
+}
+```
+
+Resolve the target env: explicit argument → `default` → infer. Then the **mutation level governs everything**:
+
+- **`read-only`** — only non-mutating interactions: read endpoints (`GET`), view UI without submitting, `cdk synth`/`diff`, `--help`/dry-run. Never create / edit / delete.
+- **`full`** — create / edit / delete allowed, but **only as the `identity` test account** and under Mutation Discipline (§5).
+- **`forbidden`** — do not exercise this environment at all.
+
+**Safety rules — enforced regardless of config:**
+
+- **No `exploration` block, or an unconfigured env → treat as `read-only`.** Never mutate without an explicit policy.
+- **A production-named env (`prod` / `production`) defaults to `forbidden`.** It may be raised to `full` **only** when a written `prodMutationAck` justification is present (this is how a single-environment app — e.g. a local-only game whose only "env" is production and whose mutations are the user's own local save — deliberately opts in). A bare `production: { "mutation": "full" }` with **no** `prodMutationAck` is downgraded to `forbidden`, and you warn.
+- **Never sign in as a real user or an admin** — only the `identity` test account.
+- If evaluating something *requires* a mutation the policy forbids, stop at that boundary and report it — never escalate your own permissions.
+
+## 3. Discover personas & subagents — soft-detect
+
+Look for the project's personas: `wiki/personas/**` (target-player archetypes, stakeholders) and persona subagents (e.g. the `lisa-phaser` `target-player` / `player-advocate` agents).
+
+- **Present** → drive the product **through each relevant persona**: adopt the archetype's constraints (device, session length, goals, patience, genre-literacy) and evaluate as them; run each archetype for breadth.
+- **Absent** → drive as a single **generic representative end user** of the app's stated audience, and say so.
+
+## 4. Drive the product — per type
+
+Apply the interface's *read-only* actions always; the *mutate* actions only when the policy is `full`.
+
+- **DOM web app** — a real browser (Playwright MCP). Land cold on the entry page, then click / type / select / submit visible controls and attempt real tasks; sweep viewport widths. *(The caller's lens supplies the specific things to look for.)*
+- **HTTP / API backend** — the consumer is a client, not a browser. Read-only: read the OpenAPI/routes and call safe `GET`s (`curl`/`httpie`). Mutate: exercise representative `POST`/`PUT`/`DELETE` flows with test data as the `identity`; check status codes, payload shapes, and error responses.
+- **Canvas game** — a real browser, but the UI is **drawn to a canvas, not the DOM**. Boot it (e.g. `bun run dev` + Playwright), drive via **keyboard/pointer into the canvas**, and read state **visually via screenshots** (not the accessibility tree). Mutation is usually local save state. Judge readability, game-feel, and input responsiveness — not DOM breakpoints.
+- **CLI / library** — the interface is the command / public API. Read-only: `--help`, read-only commands, dry-runs. Mutate: run state-changing commands with disposable inputs.
+- **IaC / CDK** — the "user" is whoever **consumes the resources the stack provisions** (plus the operator). **Read-only (default):** `cdk synth` → read the generated template; `cdk diff` vs. the deployed env; verify the resources, IAM, and outputs express what a consumer would expect. Flag over-broad IAM, missing/opaque outputs, resources that don't serve their stated purpose, and drift. **Mutate (only when `mutation: "full"` *and* `provision: true` on an ephemeral/sandbox env):** `cdk deploy` to the sandbox → recurse into the API/web playbook against the provisioned resources → `cdk destroy`. Never deploy to a real account without explicit sandbox-provisioning config.
+
+## 5. Mutation Discipline — only when the policy is `full`
+
+A real user creates, edits, and deletes things — exercise those flows when, and only when, the policy allows and always as the `identity` account.
+
+- Use unique names with a clear prefix such as `qa-` or `codex-`.
+- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up, then verify it. If cleanup is unavailable, that itself is a finding.
+- Avoid destructive bulk actions unless the account/data is clearly disposable.
+- Record every mutation performed, cleanup attempts, and any residue left behind.
+
+## What you return
+
+Structured, raw observations for the caller — **what** you did, **as whom** (which persona / generic user), **where** (env + mutation level), **what you saw**, and **what you could not reach and why** (especially policy boundaries you stopped at). You do **not** file tickets or write plans; the caller does.

package/plugins/src/expo/commands/e2e-coverage-gaps.md

@@ -4,4 +4,4 @@ allowed-tools: ["Skill"]
 argument-hint: "[target-url | env] [ready=true|false]"
 ---
 
-Use the /lisa-expo:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-expo:exploratory-qa. $ARGUMENTS
+Use the /lisa-expo:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa:exploratory-qa. $ARGUMENTS

package/plugins/src/harper-fabric/commands/e2e-coverage-gaps.md

@@ -4,4 +4,4 @@ allowed-tools: ["Skill"]
 argument-hint: "[target-url | env] [ready=true|false]"
 ---
 
-Use the /lisa-harper-fabric:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-harper-fabric:exploratory-qa. $ARGUMENTS
+Use the /lisa-harper-fabric:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa:exploratory-qa. $ARGUMENTS

package/plugins/src/rails/commands/e2e-coverage-gaps.md

@@ -4,4 +4,4 @@ allowed-tools: ["Skill"]
 argument-hint: "[target-url | env] [ready=true|false]"
 ---
 
-Use the /lisa-rails:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-rails:exploratory-qa. $ARGUMENTS
+Use the /lisa-rails:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa:exploratory-qa. $ARGUMENTS

package/plugins/lisa-expo/commands/exploratory-qa.md

@@ -1,7 +0,0 @@
----
-description: "Run a first-time-user exploratory QA walkthrough: experience the app like a brand-new human user in a real browser or browser automation session, clicking/typing/selecting through visible controls to find anything confusing, broken, or hard to understand (human-facing jargon, contextless extracted data, machine-style labels, slow or unclear loads, late meaningful content, cramped or cut-off UI, inconsistent UX, awkward scroll behavior) across all breakpoints, and file each finding (bug or usability issue) as a tracked work item via lisa:tracker-write. Static scans, HTTP fetches, screenshots alone, or console/network checks alone are not sufficient. The optional ready flag marks tickets build-ready (auto-picked-up by lisa:intake) or leaves them in the backlog for human triage (default). For gaps in the automated Playwright suite, use e2e-coverage-gaps instead."
-allowed-tools: ["Skill"]
-argument-hint: "[target-url | env] [ready=true|false]"
----
-
-Use the /lisa-expo:exploratory-qa skill to experience the app like a brand-new first-time user in a real browser or browser automation session — landing cold on the home page, clicking/typing/selecting through visible controls, and verifying resulting UI state across all breakpoints — and file each finding (bugs, usability/clarity issues) as a tracked work item via lisa:tracker-write, build-ready or in triage per the ready flag (default: triage). Static scans, HTTP fetches, screenshots alone, or console/network checks alone are not enough. For automated Playwright coverage gaps, use /lisa-expo:e2e-coverage-gaps. $ARGUMENTS

package/plugins/lisa-expo/skills/exploratory-qa/SKILL.md

@@ -1,264 +0,0 @@
----
-name: exploratory-qa
-description: First-time-user exploratory QA walkthrough for web apps that FEEDS THE LIFECYCLE. Use when asked to experience an app the way a brand-new human user would — opening it in a real browser or browser automation session, landing cold on the home page, and clicking/typing/selecting through visible controls to find anything confusing, broken, or hard to understand (unclear purpose or audience, human-facing jargon, contextless extracted data, machine-style labels, raw dates/enums, sparse data with no explanation, wrong control semantics, slow or unclear loads, late meaningful content, cramped or cut-off UI, inconsistent/non-standard UX, awkward scroll behavior, unclear affordances, dead-end flows that strand a user — e.g. a login page with no way to register or recover a password, or a primary action that drops the user into an incomplete/unsatisfiable state with no way to finish) across all breakpoints. Static route scans, HTTP fetches, screenshots alone, or console/network checks alone are not sufficient exploratory QA evidence. Instead of writing a report file, it files every finding as a tracked work item via lisa:tracker-write (bugs and usability/UX issues). A `ready` parameter controls whether those tickets are created build-ready (auto-picked-up by lisa:intake) or left in the backlog for human triage (default). For gaps in the automated Playwright test suite, use the e2e-coverage-gaps skill instead.
----
-
-# Exploratory QA
-
-## Overview
-
-Experience the app the way a **brand-new human user** would: open it in a real browser or browser
-automation tool, land cold on the home page with no prior knowledge, then click through and actually
-try to use it — just like a real person. The goal is to surface anything **confusing, broken, or hard
-to understand**, and to do so at **every breakpoint**.
-
-This is a usability/experience pass, **not** a test-coverage audit. It does not look at the Playwright
-suite or hunt for coverage gaps — for that, use the `e2e-coverage-gaps` skill. Here, every finding is
-filed as a tracked work item so it enters the Lisa lifecycle — no static report file. Static route
-scans, HTTP fetches, screenshots alone, and console/network checks alone do not count as exploratory
-QA evidence because they do not prove a person could use the visible UI.
-
-## Parameters
-
-- **`target-url | env`** (first positional) — what to explore.
-- **`ready=true|false`** — the build-ready state for the tickets this pass creates.
-  - `ready=true` → created build-ready, so `lisa:intake` / the build-intake scanner auto-picks them up.
-  - `ready=false` (**default**) → created in the backlog (not build-ready) for a human to review and
-    promote into the queue.
-
-## Core Workflow
-
-### 1. Establish Scope
-
-- Identify the target environment, account type, and browser requirement, and read the `ready` flag
-  (default `false`).
-- Open the target in a real browser or browser automation tool before drawing conclusions. Use static
-  code inspection, route lists, network/console logs, and screenshots only as supporting evidence, not
-  as a substitute for live browser interaction.
-- **Confirm the tracker is configured.** Findings are filed as tickets, so read `tracker` from
-  `.lisa.config.json` (local overrides global). If it is unset, stop and report that the tracker must
-  be configured (via `/lisa:setup:jira` / `:github` / `:linear`) before exploratory QA can file
-  findings — do not silently fall back to a report file.
-- If credentials, tenant, or seed data are missing and cannot be discovered safely, ask one concise
-  clarifying question.
-- Treat production-like environments conservatively. Do not mutate production data unless the user
-  explicitly approves it. Prefer a test user, dev/staging environment, or isolated seeded account.
-
-### 2. Arrive Cold
-
-- Start at the home/landing page with **no prior knowledge of the app**. Do **not** pre-read the
-  codebase to learn the intended flows — discover them the way a user would, by looking and clicking.
-- Form a first impression: is it obvious what this app is, what to do first, and where to go next?
-- On each major page, ask what a cold user would think the page is trying to do or tell them. If the
-  page could plausibly be read as several different products or workflows (public browser vs admin
-  workbench vs data-quality dashboard vs review queue), file a clarity/usability ticket.
-
-### 3. Use It Like a Human
-
-Click through the visible paths and actually attempt real tasks in the browser — a first-time user
-explores, makes mistakes, and tries the obvious thing. When a page exposes forms, filters, menus,
-links, buttons, selects, tabs, or other visible controls, click, type, select, submit, clear,
-navigate, and otherwise exercise representative controls when safe; then verify the resulting UI or
-data state in the browser. Cover at least these dimensions unless the user narrows scope:
-
-- **Comprehension & labeling:** human-facing copy must sound like something a normal first-time user
-  would understand. Flag machine-style or developer labels shown to users (raw IDs, enum keys,
-  `snake_case`, `null`/`undefined`, untranslated i18n keys), admin/database terms such as
-  "metadata", "rows", "bucket", "record", "entity", or "loaded rows", implementation identifiers such
-  as slugs, unexplained domain jargon, unclear button/menu names, and icons with no discernible
-  meaning. Flag all-caps enum/source labels, raw timestamps, and typo-like machine strings. If a
-  heading, label, or field would make a non-technical user ask "what does that mean?", file a
-  usability/clarity ticket with plainer wording.
-- **Data usefulness & context:** extracted facts, metrics, summaries, and structured tables must help
-  a person understand the surface. Flag machine residue that only proves extraction happened, such as
-  repeated generic fields (`Money Mention`, `Entity`, `Record`) paired with values but no sentence,
-  source, category, or explanation of why the value matters. If a user cannot tell what a number,
-  fact, or field refers to without rereading the raw source, file a usability/clarity ticket to hide it
-  from the default UI or add context such as excerpts, labels, grouping, or provenance.
-- **Data volume and trust:** compare the amount of visible data to what the page promises. A rich
-  explorer, dashboard, or workbench with only a few rows/items can look broken, filtered, still
-  loading, sample-only, or untrusted. File a finding when sparse data is not explicitly explained with
-  result counts, active filters, reset affordances, ingestion/coverage status, or sample/demo labeling.
-- **Dates, numbers, and source metadata:** normal product UI should not expose storage formats unless
-  it is intentionally a technical log. Flag ISO timestamps, inconsistent relative/absolute date
-  styles, unexplained generated/imported/loaded dates, raw score/null states, and source metadata that
-  does not explain what was sourced, when, and why it matters.
-- **Controls and mental model:** controls must match what they do. Sort is not a filter; search is not
-  a facet; finite data domains usually need selects/typeaheads rather than blank text inputs. Flag
-  controls that make users guess exact spelling/casing, hide the available option universe, mix
-  filtering with sorting/view settings, or use the wrong component for the task.
-- **Information hierarchy and panel value:** scan cards, sidebars, workbenches, summaries, and metric
-  tiles for whether they communicate anything useful at a glance. File findings for blank-looking
-  panels, repeated cards with unclear labels, counts without named subjects, decorative summaries that
-  consume more attention than the primary workflow, or duplicated navigation that squeezes the actual
-  task area.
-- **Navigation clarity:** is it obvious how to get somewhere and back? Dead ends, hidden entry points,
-  surprising redirects, broken links, no clear "home". Flag duplicated nav regions that compete for
-  space without adding page-specific value, and icon systems that degrade into raw punctuation or mix
-  unrelated visual languages.
-- **Flow completeness & expected counterparts:** a screen that gates access or shows one side of a
-  standard paired flow must offer the other side — or a clear path to it. A brand-new user must never
-  hit a dead end with no next step. Flag missing companion actions, especially on auth and entry
-  screens:
-  - **Sign-in with no sign-up:** a login page with no "Create account" / "Register" link strands
-    anyone who does not already have an account; likewise a registration page with no link back to
-    sign in.
-  - **No account recovery:** login with no "Forgot password?", no way to reset, and no way to resend a
-    verification email.
-  - **No exit from a state:** a signed-in app with no visible sign-out, or a modal / wizard / detail
-    view with no back, close, or cancel.
-  - **One-way actions:** create/add with no matching edit or delete (or the reverse) where a user
-    would reasonably expect both.
-  - **Unreachable entry points:** a feature only reachable by guessing a URL, or an empty state with
-    no primary action to populate it.
-  When the missing counterpart makes a core task impossible for a whole class of users (e.g. a new
-  user literally cannot create an account), file a `Bug`; otherwise file a usability `Improvement`.
-- **Action preconditions & incomplete end-states:** an action whose result only makes sense with
-  multiple inputs (compare, merge, combine, bulk-edit) or with some prerequisite met should guide the
-  user to satisfy that precondition — by disabling/explaining it until it is met, by collecting the
-  inputs first (e.g. a selection tray), or by giving the destination an obvious in-place control to
-  complete it. Actually trigger these actions and watch where they land; flag when a primary action:
-  - **Fires under-satisfied and strands the user:** e.g. a per-row "Compare" that navigates to a
-    comparison of a single item, shows an "under limit / add at least 2" notice, but exposes no
-    visible "add another" control — the user is told what is wrong with no in-place means to fix it.
-  - **Lands on an incomplete / empty end-state with no next step:** a results or detail screen that
-    announces it is empty, partial, or "needs more" yet offers no affordance to add, retry, or return
-    to the selection that produced it.
-  - **Is offered where it cannot succeed:** a multi-item action exposed on a single item, or an action
-    left enabled while its precondition (a selection, a minimum count, a required field) is unmet,
-    with no explanation.
-  When the user is left unable to complete the action they started, file a `Bug`; when it eventually
-  works but the path is confusing or roundabout, file a usability `Improvement`.
-- **Visual/layout quality:** cut-off or truncated text, overlap, cramped/crowded density, offscreen or
-  unreachable controls, accidental horizontal scroll, awkward empty space. **Do not judge this by
-  eyeballing a screenshot alone** — a control clipped by a few pixels or pushed just past a container
-  edge looks fine in a thumbnail. Confirm it with the programmatic layout-integrity sweep in §5 at
-  every width.
-- **Consistency / standard UX:** components, spacing, button styles, terminology, and interaction
-  patterns should be consistent across the app and follow common conventions. Flag anything
-  non-standard or that differs screen-to-screen.
-- **Load & responsiveness:** long or unclear load times, blank screens, skeleton-only shells, spinners
-  / `Loading...` / `Connecting...` with no progress, anything that feels slow or janky. Flag pages
-  where the browser reports `loaded` / `complete` but meaningful content arrives much later, or where
-  the visible shell appears quickly while the real task content remains missing. Capture user-perceived
-  timings: shell visible, first meaningful content, and stable/complete content. If the delay is
-  noticeable, file a usability/performance ticket even if the eventual content is correct.
-- **Scroll behavior:** unexpected scroll position, scroll jumps, nested or locked scroll, sticky
-  elements that cover content, content that cannot be reached.
-- **Behavior correctness:** does the obvious action do what a user expects? Confusing errors, silent
-  failures, disabled controls with no explanation, state that does not persist.
-- **Affordance clarity:** can the user tell what is clickable, required, in-progress, or complete?
-
-### 4. Cover All Breakpoints
-
-- Discover breakpoints from the app (design tokens, CSS, responsive layout changes) when possible; if
-  unknown, use a practical baseline: phone, tablet/narrow, desktop, plus any app-specific cutoff.
-- **Do not test only the named breakpoints.** Clipping and overflow most often appear at the
-  *in-between* widths — where a row can no longer fit its contents but has not yet collapsed to the
-  next layout. Sweep a range of widths (e.g. 360, 390, 414, 600, 768, 834, 1024, 1280, 1440) plus a
-  few intermediate steps (e.g. ~900–1180) and re-check the key paths at each.
-- At each width, walk the key paths again and confirm the experience holds: expected
-  shell/navigation variant, critical controls visible and reachable, no unintended horizontal
-  overflow, intentional scroll containers still usable, nothing cut off or crowded.
-
-### 5. Run Layout-Integrity Checks — Don't Eyeball Alone
-
-A screenshot glance misses controls clipped by a few pixels or pushed just past a container edge. At
-**every width**, in addition to looking, take DOM measurements via the browser automation tool
-(Playwright, Chrome MCP, etc.) and treat any of these as a finding:
-
-- **Document / container overflow:** `document.documentElement.scrollWidth > clientWidth`, or a
-  horizontal scrollbar on a container that should not scroll → accidental horizontal overflow.
-- **Clipped or offscreen controls:** for every interactive control (buttons, links, inputs, selects,
-  menu items), compare its `getBoundingClientRect()` against the viewport and against each ancestor
-  that has `overflow: hidden | clip | auto | scroll`. If any edge of the control falls outside those
-  bounds, it is partially or fully clipped / unreachable — even when the page looks fine in a thumbnail.
-  This is exactly the case that gets missed: a submit/apply button whose right edge is cut off by its
-  filter card.
-- **Truncated meaningful text:** an element whose `scrollWidth > clientWidth` (or that renders an
-  ellipsis) where the hidden text carries meaning — e.g. a select showing "Any CRD state" jammed into
-  its chevron, a label cut mid-word.
-- **Colliding controls:** a label or value overlapping an adjacent control (icon, chevron, button)
-  with no gap between them.
-
-Record which width(s) trigger each, the offending element, and a screenshot. **A primary or
-interactive control that is clipped, offscreen, or unreachable is a `Bug`, not merely an
-Improvement** — a user literally cannot see or click all of it.
-
-### 6. Watch Load & Latency
-
-- Measure separate milestones: visible app shell, `document.readyState`, first meaningful
-  route-specific content, and visually stable/full route content.
-- Do not treat a visible shell, completed document, or technically clickable page as loaded if the
-  route is still blank, skeleton-only, placeholder-only, or waiting for primary data.
-- Treat skeleton-only/placeholder-only screens as loading states. If they persist for a noticeable
-  delay, they need clear progress/loading messaging that explains what is happening.
-- Treat long waits to meaningful content or stable/full content without clear progress, error, retry,
-  or cancellation as findings. Use practical labels (noticeable, slow, unacceptable) and include
-  observed durations when available.
-
-## Mutation Discipline
-
-A real first-time user creates, edits, and deletes things — exercise those flows when the environment
-is safe.
-
-- Use unique names with a clear prefix such as `qa-` or `codex-`.
-- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up through
-  the UI, then verify cleanup. If UI cleanup is unavailable, that itself is a usability finding.
-- Avoid destructive bulk actions unless the user explicitly asks or the account is clearly disposable.
-- Record all mutations performed, cleanup attempts, and any residue left behind.
-
-## Filing findings as tracked work
-
-This skill does **not** write a report file. Every finding becomes a **leaf work item** created via
-`lisa:tracker-write` (the vendor-neutral writer — it dispatches to the configured tracker and runs the
-validation gate; never call a vendor `*-write-*` skill directly). Map each finding to a type:
-
-| Finding | `issue_type` | `build_ready` |
-|---------|--------------|---------------|
-| User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |
-| **Usability / UX / clarity issue** | `Improvement` | the `ready` flag (default `false`) |
-
-A control that is **clipped, offscreen, or otherwise unreachable** (per §5) counts as broken behavior
-→ file it as a `Bug`, not an `Improvement`. Pure crowding/clarity with the control still fully usable
-is an `Improvement`.
-
-Each finding is a flat leaf (no children), so `build_ready` applies directly — pass it explicitly on
-every create. Each ticket MUST be a complete spec (the validator rejects thin tickets):
-
-- **Three-audience description** (context / business value, technical approach, stakeholder impact).
-- **For a bug:** exact reproduction steps, observed-vs-expected, the env / account / breakpoint it
-  occurred at, and console/network evidence.
-- **For a usability issue:** the observed friction (what was confusing, cramped, inconsistent, or hard
-  to understand), who it affects, **where** (route + breakpoint), and the proposed improvement.
-- **Gherkin acceptance criteria** describing the fixed behavior.
-
-### Idempotency — don't spam duplicates
-
-Re-running a pass must not refile the same finding. Before creating a ticket, search the tracker for an
-**open** ticket carrying a stable marker `[lisa-exploratory-qa] <finding-key>` in its body (the
-`<finding-key>` is a stable slug of surface + symptom, e.g. `settings-modal/horizontal-overflow@tablet`).
-If one exists, reference/update it instead of creating a duplicate; only create when none exists.
-**Match by the marker, never by title** (titles get edited). A *closed* prior ticket does not suppress a
-new one — a recurrence after a fix is a genuine regression.
-
-## Output
-
-No report file. Emit a concise in-session summary:
-
-- **Scope:** target URL/env, browser/tool, account type, build/version if visible, date.
-- **First impression:** could a new user tell what the app is and what to do first?
-- **Findings filed**, bucketed by type — bugs, usability/clarity issues — each with its **created or
-  referenced ticket ref** and its **build-ready state** (`ready` vs `triage/backlog`).
-- **Observed but not filed:** anything noticed but intentionally not ticketed, with why.
-
-## Quality Bar
-
-- Explore as a true first-time user — judge clarity, not whether you (who can read the code) can figure
-  it out.
-- Prefer concrete, reproducible findings. Every ticket must stand alone for an implementer who was not
-  in the session.
-- Do not claim cleanup succeeded unless verified.
-- File tickets per the `ready` flag (default: backlog for human triage).
-- This skill is about the human experience only — route automated-coverage gaps to `e2e-coverage-gaps`.
-- Preserve unrelated repo changes.

package/plugins/lisa-expo/skills/exploratory-qa/agents/openai.yaml

@@ -1,4 +0,0 @@
-display_name: "Exploratory QA"
-short_description: "First-time-user exploratory QA walkthrough for web apps that FEEDS THE LIFECYCLE"
-default_prompt:
-  - "Use $exploratory-qa: First-time-user exploratory QA walkthrough for web apps that FEEDS THE LIFECYCLE."

package/plugins/lisa-expo-agy/commands/exploratory-qa.md

@@ -1,7 +0,0 @@
----
-description: "Run a first-time-user exploratory QA walkthrough: experience the app like a brand-new human user in a real browser or browser automation session, clicking/typing/selecting through visible controls to find anything confusing, broken, or hard to understand (human-facing jargon, contextless extracted data, machine-style labels, slow or unclear loads, late meaningful content, cramped or cut-off UI, inconsistent UX, awkward scroll behavior) across all breakpoints, and file each finding (bug or usability issue) as a tracked work item via lisa:tracker-write. Static scans, HTTP fetches, screenshots alone, or console/network checks alone are not sufficient. The optional ready flag marks tickets build-ready (auto-picked-up by lisa:intake) or leaves them in the backlog for human triage (default). For gaps in the automated Playwright suite, use e2e-coverage-gaps instead."
-allowed-tools: ["Skill"]
-argument-hint: "[target-url | env] [ready=true|false]"
----
-
-Use the /lisa-expo:exploratory-qa skill to experience the app like a brand-new first-time user in a real browser or browser automation session — landing cold on the home page, clicking/typing/selecting through visible controls, and verifying resulting UI state across all breakpoints — and file each finding (bugs, usability/clarity issues) as a tracked work item via lisa:tracker-write, build-ready or in triage per the ready flag (default: triage). Static scans, HTTP fetches, screenshots alone, or console/network checks alone are not enough. For automated Playwright coverage gaps, use /lisa-expo:e2e-coverage-gaps. $ARGUMENTS