@codyswann/lisa 2.61.1 → 2.62.0

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

@@ -1,19 +1,30 @@
 ---
 name: exploratory-qa
-description: Playwright-backed exploratory QA workflow for web apps. Use when asked to audit an app or project with Playwright/e2e tests, find human-noticeable bugs, identify gaps in automated test coverage, test responsive breakpoints, observe slow or unclear load states, exercise mutable workflows with cleanup, or produce a QA gaps report.
+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.
 ---
 
 # Exploratory QA
 
 ## Overview
 
-Run a human-style exploratory QA pass informed by the existing Playwright suite. The goal is to find issues users notice and machines often miss, then translate those observations into actionable Playwright coverage gaps.
+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.
+
+## 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.
+  - `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`.
 
 ## Core Workflow
 
 ### 1. Establish Scope
 
-- Identify the target environment, account type, browser requirement, and requested report path.
+- 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.
@@ -57,7 +68,7 @@ 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, record that as a product/test gap. Use documented API cleanup only if appropriate for the project and account.
+- 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.
 
@@ -83,26 +94,45 @@ Measure perceived latency, not just eventual success.
 - 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.
 
-## Report Structure
+## 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:
+
+| 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.
+
+Each ticket MUST be a complete spec (`lisa:tracker-write` runs the validator and 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.
+
+### 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.
 
-Write the report to the user's requested path. If none is specified, use a clear local name such as `PLAYWRIGHT_GAPS.md` or `EXPLORATORY_QA_REPORT.md`.
+## Output
 
-Include:
+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, thin areas, skipped tests, viewport/browser matrix, mutation coverage.
-- Exploratory findings: steps, observed behavior, impact, why existing tests miss it, recommended test.
-- Breakpoint findings: exact viewports tested and boundary behavior.
-- Load-state findings: observed delays, blank/spinner/connecting states, suggested budgets/tests.
-- Mutation findings: data created, behavior observed, cleanup attempt, cleanup result, residue.
-- Missing Playwright tests to add: prioritized, concrete, and automatable.
-- Maintenance notes: selector scoping, fixture cleanup, flaky/stale-state risks.
+- **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`).
+- **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.
-- Prefer concrete examples over vague recommendations.
+- 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.
 - Do not claim cleanup succeeded unless verified.
 - Do not let broad locators pass against hidden/inactive content.
-- Preserve unrelated repo changes and keep report edits scoped.
+- File missing-test tickets build-ready; file bug and usability tickets per the `ready` flag (default: backlog for human triage).
+- Preserve unrelated repo changes.

package/plugins/src/wiki/skills/lisa-wiki-ingest/SKILL.md

@@ -19,6 +19,24 @@ performs the shared, ordered pipeline.
   run includes explicit external-write intent**.
 - **Dry run:** `/ingest --dry-run` — list the sources a full ingest would run; perform no writes.
 
+## Before ingesting — sync the branch (once per run)
+
+Run this **once per ingest invocation, before any source is processed** (skip for `--dry-run`, which
+writes nothing). The point is to ingest on top of fresh state, never stale state.
+
+1. **Resolve the default remote branch** — `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`,
+   or `git remote show origin | sed -n 's/.*HEAD branch: //p'`, or the `origin/HEAD` symbolic ref. If
+   the repo has no remote, note "no remote — skipping branch sync" and proceed.
+2. **Fetch** — `git fetch <remote>` to update remote-tracking refs.
+3. **Bring the working branch up to date with the default remote branch** so the ingest lands on
+   current state:
+   - On the default branch → fast-forward to `<remote>/<default>` (`git pull --ff-only`).
+   - On a non-default branch → merge or rebase `<remote>/<default>` in (per the project's convention)
+     so the branch is not behind the default.
+4. If the sync cannot complete cleanly (merge conflict, diverged history, or a dirty tree that would
+   conflict), **stop and surface it** rather than ingesting on top of stale or conflicted state — the
+   human resolves and re-runs. **Never discard unrelated working-tree changes** to force a sync.
+
 ## The ordered pipeline (per source) — never reorder
 1. **Connector** validates (tenant guard + auth), reads its state cursor (first-run vs incremental),
    fetches read-only, and writes a sanitized **source note** under `wiki/sources/<system>/` plus run
@@ -29,9 +47,20 @@ performs the shared, ordered pipeline.
 4. **Log**: append a `wiki/log.md` entry (fixed operation vocabulary).
 5. **Verify**: `git diff --check`, secret/tenant/contamination scans, touched-file guard.
 6. **State**: advance the connector's `wiki/state/<system>/*.json` cursor — only now, after 1–5 pass.
-7. **Commit/PR**: per `config.git` policy. `external-write` runs and sensitive content never auto-merge.
+7. **Commit/PR**: commit only the ingestion changes per `config.git` policy. If the ingest started on
+   the default branch, create a dedicated ingestion branch first — never commit ingestion straight to
+   the default. Push the branch and **open a PR targeting the default remote branch** (via the host's
+   PR mechanism — e.g. `gh pr create --base <default>`), then **enable auto-merge when possible**
+   (`gh pr merge --auto`, or the host's equivalent). `external-write` runs and sensitive content are
+   the exception — open the PR **without** auto-merge so a human reviews them before it lands. If
+   auto-merge cannot be enabled (the host doesn't support it, or branch protection forbids it), leave
+   the PR open and note that a human must merge.
 
 ## Rules
+- **Bookend every ingest with git hygiene:** sync the branch with the default remote branch *before*
+  writing (see "Before ingesting"), and *after* a successful ingest open a PR to the default remote
+  branch with auto-merge enabled when possible — never auto-merging `external-write`/sensitive runs.
+  `--dry-run` does neither (it writes nothing).
 - Source-note-before-synthesis; state advanced **only** after verification.
 - Project-scoped only; memory ingestion never touches global/Codex-global stores.
 - Respect `sourceRetention` and `sensitivity`; do not invent facts.