@codyswann/lisa 2.110.0 → 2.111.0

package/plugins/src/rails/skills/exploratory-qa/SKILL.md

@@ -1,138 +1,145 @@
 ---
 name: exploratory-qa
-description: Playwright-backed exploratory QA workflow for web apps that FEEDS THE LIFECYCLE. Use when asked to audit an app with Playwright/e2e tests, find human-noticeable bugs and usability issues, identify gaps in automated test coverage, test responsive breakpoints, observe slow or unclear load states, or exercise mutable workflows with cleanup. Instead of writing a report file, it files every finding as a tracked work item via lisa:tracker-write (bugs, usability suggestions, and missing Playwright tests). A `ready` parameter controls whether bug and suggestion tickets are created build-ready (auto-picked-up by lisa:intake) or in the backlog for human triage (default); missing-test tickets are always created build-ready.
+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 — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent/non-standard UX, awkward scroll behavior, unclear affordances) across all breakpoints. 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
 
-Run a human-style exploratory QA pass informed by the existing Playwright suite, then **file every finding as a tracked work item** in the project's configured tracker so it enters the Lisa lifecycle. The goal is to find issues users notice and machines often miss — bugs, usability friction, and coverage gaps — and turn each into actionable, automatable work, not a static report.
+Experience the app the way a **brand-new human user** would: 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.
 
 ## Parameters
 
-- **`target-url | env`** (first positional) — what to audit.
-- **`ready=true|false`** — the build-ready state for the **bug** and **usability/suggestion** tickets this pass creates.
+- **`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.
-  - **Missing Playwright test tickets are ALWAYS created build-ready, regardless of this flag** — adding missing coverage is always safe to queue.
-
-`ready` maps directly to the `build_ready` write-control input on `lisa:tracker-write`.
+  - `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, browser requirement, and the `ready` flag value (default `false`).
-- **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, seed data, or mutation boundaries are missing and cannot be discovered safely, ask a 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 for mutation testing.
-
-### 2. Research Existing Playwright Coverage
-
-- Inspect Playwright config, auth/setup projects, fixtures, constants, selectors, test directories, skipped tests, retries, and viewport/device projects.
-- Summarize:
-  - Number and shape of specs/tests.
-  - Major workflows covered well.
-  - Skipped/flaky/TODO coverage.
-  - Viewports and browser projects used.
-  - Mutating tests and their cleanup strategy.
-  - Areas where tests assert presence instead of behavior.
-- Use existing test helpers/selectors when exploring the app. They reveal intended flows and stable hooks.
-
-### 3. Choose Browser Tools
-
-- Use the user's requested browser/tool when specified.
-- Use a real profile browser when the task depends on existing cookies, SSO, extensions, or a logged-in session.
-- Use Playwright automation when exact viewport sizing, repeatable navigation, screenshots, console logs, traces, or route timing are needed.
-- Do not let automation hide human observations. Screenshots, visible text, layout, latency, scrollability, and affordance clarity matter.
-
-### 4. Explore Like A Human
-
-Cover at least these dimensions unless the user narrows scope:
-
-- **Navigation:** direct URLs and visible click paths.
-- **Responsive behavior:** supported breakpoints, plus boundary widths where layout changes.
-- **Visual/layout quality:** cutoff text, overlap, offscreen controls, accidental horizontal scroll, empty space, awkward density, hidden stale content.
-- **Load states:** blanks, skeletons, spinners, `Loading...`, `Connecting...`, delayed hydration, and whether delays exceed a human-acceptable threshold.
-- **Behavior correctness:** sorting, filtering, saving, deleting, disabled states, permissions, tab persistence, URL canonicalization.
-- **Accessibility/testability:** hidden or off-canvas content exposed to accessibility/text locators, duplicate inactive route content, zero-sized interactive elements.
-- **Console/network health:** errors, missing assets, failed requests, noisy expected errors that could bury real failures.
-- **Data hygiene:** repeated test artifacts, stale seeded content, polluted shared accounts.
+- Identify the target environment, account type, and browser requirement, and read the `ready` flag
+  (default `false`).
+- **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?
+
+### 3. Use It Like a Human
+
+Click through the visible paths and actually attempt real tasks — a first-time user explores, makes
+mistakes, and tries the obvious thing. Cover at least these dimensions unless the user narrows scope:
+
+- **Comprehension & labeling:** machine-style or developer labels shown to users (raw IDs, enum keys,
+  `snake_case`, `null`/`undefined`, untranslated i18n keys), jargon, unclear button/menu names, icons
+  with no discernible meaning.
+- **Navigation clarity:** is it obvious how to get somewhere and back? Dead ends, hidden entry points,
+  surprising redirects, broken links, no clear "home".
+- **Visual/layout quality:** cut-off or truncated text, overlap, cramped/crowded density, offscreen or
+  unreachable controls, accidental horizontal scroll, awkward empty space.
+- **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, spinners / `Loading...` /
+  `Connecting...` with no progress, anything that feels slow or janky.
+- **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.
+- At each breakpoint, 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. Watch Load & Latency
+
+- Notice time to first meaningful content and time spent in blank/loading/spinner/connecting states.
+- A page can be technically interactive but still visually incomplete — note that.
+- Treat long waits without clear progress, error, retry, or cancellation as findings. Use practical
+  labels (noticeable, slow, unacceptable) and include observed durations when available.
 
 ## Mutation Discipline
 
-Exploratory QA should exercise mutable workflows when the environment is safe.
-
-- Prefer high-value user workflows: create/edit/delete records, lists, boards, tags, notes, comments, scenarios, uploads, messages, settings, invitations, or assignments.
-- Use unique names with a clear prefix such as `qa-`, `pw-`, 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, file that as a product/test gap (a finding — see below). Use documented API cleanup only if appropriate for the project and account.
-- Record all mutations performed, cleanup attempts, and residue left behind.
-- Avoid destructive bulk actions unless the user explicitly asks or the test account is clearly disposable.
-
-## Breakpoint Strategy
-
-- Discover breakpoints from the codebase, design tokens, CSS, docs, or Playwright constants when possible.
-- Test each named breakpoint and the boundary on both sides of important cutoffs.
-- If breakpoints are unknown, use a practical baseline: phone, tablet/narrow, desktop, and any app-specific cutoff discovered during research.
-- For each breakpoint, assert both user-visible behavior and automation-relevant state:
-  - Expected shell/navigation variant.
-  - Route-specific loaded content.
-  - Critical controls visible and reachable.
-  - No unintended document-level horizontal overflow.
-  - Intentional scroll containers remain usable.
-  - Hidden/off-canvas UI is not exposed as active content.
+A real first-time user creates, edits, and deletes things — exercise those flows when the environment
+is safe.
 
-## Load-State Strategy
-
-Measure perceived latency, not just eventual success.
-
-- Track time to shell, time to meaningful route content, and time spent in blank/loading/spinner/connecting states.
-- Note when a page is technically interactive but still visually incomplete.
-- Treat long waits without clear progress, error, retry, or cancellation as bugs or test gaps.
-- Do not overfit exact milliseconds unless the project has defined budgets. Use practical labels such as noticeable, slow, or unacceptable and include observed durations when available.
+- 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 and a build-ready state:
+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** | `Bug` | the `ready` flag (default `false`) |
-| **Usability / UX issue** (suggestion) | `Improvement` | the `ready` flag (default `false`) |
-| **Missing Playwright test** (coverage gap) | `Task` | **`true` (always)** |
-
-Each finding is a flat leaf (no children), so `build_ready` applies directly. Pass it explicitly on every create — `build_ready: <ready flag>` for bugs and suggestions, `build_ready: true` for missing tests.
+| User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |
+| **Usability / UX / clarity issue** | `Improvement` | the `ready` flag (default `false`) |
 
-Each ticket MUST be a complete spec (`lisa:tracker-write` runs the validator and rejects thin tickets):
+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, who it affects, and the proposed improvement.
-- **For a missing test:** the user behavior the test must assert and the stable selector/flow to use — concrete and automatable.
-- **Gherkin acceptance criteria** describing the fixed (bug / usability) or added (test) behavior.
+- **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 QA 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.
+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.
-- **Existing Playwright coverage:** strengths and thin areas observed during research.
-- **Findings filed**, bucketed by type — bugs, usability suggestions, missing tests — each with its **created or referenced ticket ref** and its **build-ready state** (`ready` vs `triage/backlog`).
+- **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
 
-- Be honest about what was and was not tested.
-- Distinguish user-visible bugs from missing automated coverage — they map to different issue types (`Bug` vs `Task`).
-- Prefer concrete, reproducible findings. Every ticket must stand alone for an implementer who was not in the session.
+- 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.
-- Do not let broad locators pass against hidden/inactive content.
-- File missing-test tickets build-ready; file bug and usability tickets per the `ready` flag (default: backlog for human triage).
+- 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/src/wiki/templates/llm-wiki-contract.md

@@ -23,6 +23,18 @@ Repository mode: **{{mode}}**.
 - `{{wikiRoot}}/staff/` — digital-staff role pages (optional).
 - Synthesis categories: {{categories}}.
 
+## Answering questions (query-first)
+When you need to answer a question about this project — its code, architecture, decisions, domain
+concepts, conventions, or documentation — reach for the wiki **first**: run `/query "<question>"`
+(Codex: `$lisa-wiki-query`) before ad-hoc code search, grep, or a web lookup. The wiki is the
+curated, cited source of truth for this project, so a query is usually faster and more accurate than
+re-deriving the answer from raw files.
+
+This is the **primary** method, not the only one. If `/query` returns nothing relevant, the answer
+is not in the wiki yet, or the question is about live/uncommitted state, fall back to reading the
+code, browsing `{{wikiRoot}}/index.md`, or other tools — and consider `/ingest` to capture any
+durable knowledge you had to reconstruct so the next query succeeds.
+
 ## Ordered ingestion pipeline (never reorder)
 `source note → synthesis → index → log → verify → state → commit/PR`.
 State advances **only** after source notes + synthesis + index + log + verification all pass.