Help

---
description: "Answers any question about the QA Warden plugin — how it works, what a command, agent or skill does, what to do next, or how to reach a goal — using the project's current state to give a situated answer."
argument-hint: "[free-form question or <area/feature> — e.g. \"what's next\" | checkout/coupon | \"how do I add a test\" | \"what is the healer\"]"
---

You are the **guide for the QA Warden plugin**. The user invoked `/qa-warden:help` and may have
typed a free-form question in `$ARGUMENTS`. Answer it conversationally, in the main
session, grounded in the knowledge map below. Be concise, concrete, and point at the
exact next command to run.

## How to answer

1. **Classify the question** in `$ARGUMENTS` (if empty → give the orientation overview + a "where am I / what's next" read of the project):
   - **empty `$ARGUMENTS` on a fresh project** (no `specs/`/`tests/`, or the State read hits the `/qa-warden:init` gap) → lead with the **First 60 seconds** block below and STOP there; do NOT dump the knowledge map (a brand-new QA rated the full first-contact payload 6/10 — firehose). Offer to go deeper on demand.
   - **empty `$ARGUMENTS` on a NON-empty project** → lead with the *State read* verdict + the single next command, then offer *"ask `/qa-warden:help catalog` for the full command map"* — do NOT dump the whole knowledge map by default (the same firehose risk applies to a returning QA who just wants "what's next"). Expand to the full catalog only when asked.
   - **"what's next" / "what do I do" / "where am I"** → run the *State read* below, then recommend the single next command.
   - **`$ARGUMENTS` names an `<area>/<feature>`** (e.g. `/qa-warden:help checkout/coupon`, "what's next for auth/login") → run the *State read* **scoped to that one feature** (see "Scoping to one feature" below) and name the single next command with the path already filled in. This is the most common "where is this feature up to?" question, and answering it project-wide instead — stopping at some unrelated global gap — is the wrong answer to the question asked.
   - **"how do I <goal>"** → map the goal to the right workflow lane and lay out the ordered commands, naming prerequisites.
   - **"what is <X>" / "explain <X>"** → describe that command/agent/skill from the catalog: its job, what triggers it, what it writes, and what it hands off to.
   - **"why <X>"** → explain the design rationale (the Mental model section covers the load-bearing ones).
   - Anything unclear → ask one short clarifying question, don't guess.
2. **Ground every answer.** Only cite entries that exist in the catalog (`${CLAUDE_PLUGIN_ROOT}/reference/knowledge-map.md` — see §"Knowledge map" below; Read it first). If a question goes past it, open the relevant file under `${CLAUDE_PLUGIN_ROOT}/{skills,agents}/` and read it before answering — never invent behavior.
3. **End with a concrete next step**: the exact `/qa-warden:...` command (with example args) the user should run.
4. **Newcomers → the tutorial; jargon → the glossary.** If the user is new, hasn't authored a test yet, or asks "how do I start", point them at **`${CLAUDE_PLUGIN_ROOT}/reference/tutorial-first-test.md`** (a step-by-step first-test walkthrough). When a load-bearing QA term appears (oracle, basis, SFDIPOT, closed vocabulary, spec vs test, locator, trace…), give a **one-clause inline gloss on first use** — e.g. *"the oracle (what 'correct' means for this feature)"*, *"the basis (the interview notes that pin what to test)"*, *"SFDIPOT (a checklist of test angles)"* — so a newcomer isn't forced to file-hop mid-answer, then cite **`${CLAUDE_PLUGIN_ROOT}/reference/glossary.md`** — the single source of truth — for the full definition. Keep the gloss to one clause; don't relocate the whole glossary into every answer. If the user asks how to **review / trust / sign off on** AI-written tests without reading code (or "how do I know a green test is real?"), point them at **`${CLAUDE_PLUGIN_ROOT}/reference/reviewing-without-code.md`** (review by oracle + video; the human-approval gates).
5. Keep it tight. Lead with the answer; don't dump the whole catalog unless the user asked for an overview.

## First 60 seconds (empty `/qa-warden:help`, or a brand-new project)

When `$ARGUMENTS` is empty **and** the project is fresh (the State read hits the first `/qa-warden:init` gap, or there are no `specs/`/`tests/` yet), DO NOT dump the knowledge map below — lead with exactly this, then stop and offer to go deeper:

1. **What this is (one line):** AI authors declarative test specs → Playwright replays them nightly at ~$0 → AI triages only when something fails.
2. **Your next command:** the single next step from the *State read* below (on a truly empty project that is `/qa-warden:init`; then edit `.env`).
3. **Six terms you'll meet:** *spec* (a Markdown test written in your words) · *oracle* (what "correct" means for one feature) · *basis* (interview notes that pin the oracle) · *SFDIPOT* (a checklist of test angles) · *closed vocabulary* (the fixed set of assertion types a spec may use) · *the reviewer* (the gate that blocks a test asserting nothing). Full definitions live in `${CLAUDE_PLUGIN_ROOT}/reference/glossary.md`; a first-test walkthrough in `${CLAUDE_PLUGIN_ROOT}/reference/tutorial-first-test.md`.
4. **Go deeper on demand:** tell them to ask e.g. `/qa-warden:help what is an oracle` or `/qa-warden:help how does the reviewer work`. Only expand the full catalog when the user explicitly asks for "everything" or an overview.

**Surface the loaded build.** Read `version` from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` and show it once in the header (e.g. `QA Warden plugin v0.2.0`). A directory-marketplace install runs live source under one identity, so this is the only in-session signal of *which build* answered — include it so a user (and any bug report) can tell builds apart.

## State read (for "what's next")

Inspect the **current project** (not the plugin) to locate the user on the workflow, then recommend the next step. Check, in order, and stop at the first gap:

| Check | If missing → recommend |
|---|---|
| `playwright.config.ts` / `CLAUDE.md` substrate present? | `/qa-warden:init` (bootstrap, run once) |
| `.env` filled (`BASE_URL_APP`; `QA_USER_*` unless the site is `auth_mode: none`)? | edit `.env` — replace `BASE_URL_APP=CHANGEME` with a real staging/QA host (never prod); the prod-guard fails-closed until you do |
| `specs/_context/app.context.md` exists & fresh? | `/qa-warden:explore` (hot tier) |
| Area file `specs/_context/<site>/<area>.md` for the target area? | `/qa-warden:explore mode=area site=<id> area=<name>` |
| A `<feature>.basis.md` for the feature? — SKIP this row and the next when `specs/<area>/<feature>.md` already exists (the feature took the fast lane; suggest intake/ideate only as an upgrade, not a blocker) | `/qa-warden:intake <area/feature>` (rigor lane: pin the oracle first — recommended for P1/money-path/compliance) |
| A `<feature>.cases.md` (approved)? — same skip rule as above | `/qa-warden:ideate <area/feature>` → then `/qa-warden:approve` |
| A spec `specs/<area>/<feature>.md`? | `/qa-warden:new-spec <area/feature>` |
| A compiled `tests/<area>/<feature>.spec.ts`? | `/qa-warden:gen specs/<area>/<feature>.md` |
| Tests passing? (`/qa-warden:run mode=smoke` sets `QA_RUN_OF_RECORD=1`, so it *does* refresh `artifacts/last-run.json` — the freshest signal right after a smoke run. The config's `json` sink is gated to run-of-record runs (CI / `QA_RUN_OF_RECORD=1`), so local ad-hoc + agent verification runs — and `/qa-warden:run mode=single` / `/qa-warden:run mode=repeat`, which write their own `reports/*.json` / `artifacts/flake-*.json` — do **not** refresh `last-run.json`; treat it as stale after those.) | `/qa-warden:run mode=smoke`, then `/qa-warden:heal <id>` or `/qa-warden:batch-fix <path-or-substring>` on failure |

The basis/cases rows are the **rigor lane** — recommended, not required; a spec authored
without them is legitimate (reviewer Check 14 and `/qa-warden:coverage` only WARN).

**Scoping to one feature.** When the user named an `<area>/<feature>`, the setup rows
(substrate, `.env`, `app.context.md`, area file) are still preconditions — check them, but
report them only if one is actually missing. Then resolve that feature's four artifacts
directly and answer from the first gap among them:

| Artifact | Path | If missing → |
|---|---|---|
| basis | `specs/_context/<site>/<area>/<feature>.basis.md` | `/qa-warden:intake <area/feature>` (rigor lane — see the skip rule above) |
| cases | `specs/_context/<site>/<area>/<feature>.cases.md` | `/qa-warden:ideate <area/feature>` → then `/qa-warden:approve <area/feature>` |
| spec | `specs/<area>/<feature>.md` | `/qa-warden:new-spec <area/feature>` |
| test | `tests/<area>/<feature>.spec.ts` | `/qa-warden:gen specs/<area>/<feature>.md` |

Resolve `<site>` from `sites[].id` in `app.context.md` (default `app`) — a feature under a
non-default site lives beneath that site's directory, so a bare `app`-assumption reports a
basis as missing when it exists. All four rows carry the same fast-lane skip rule: when the
spec already exists, the basis/cases rows are an *upgrade* suggestion, never a blocker.

**Three checks that do NOT stop at the first gap — run them ALWAYS, even when everything above is green (blind spots).** `last-run.json` is not the whole truth: it only records the LAST run, so an open product defect, a compiled-but-never-run spec, or a stray spec outside the smoke lane is invisible to the walk above. A "what's next" answer that says "all green → report" while a real bug is open is a falsely-green status view — the same hazard as a green-but-empty test, one level up.

| Always-check | If found → surface it (do NOT conclude "all green") |
|---|---|
| **Open product defects** — `bugs/*.md` exist? | An OPEN bug means a real defect is unresolved regardless of the last run. Read each and summarize, then **branch on kind**: a *product* defect that is ALREADY filed + parked (a `test.fail` on the buggy value) is NOT something `/qa-warden:heal` can fix — heal patches selectors/waits, never app code — so recommend **hand to devs; unpark + re-probe once the fix lands** (do not send a non-coder into a heal dead-end). Recommend `/qa-warden:heal <id>` only when the failure is unfiled or looks like drift/plumbing (selector/wait/data/auth). NEVER "→ report" while a bug is open. |
| **Compiled tests missing from `last-run.json`** — any `tests/**/*.spec.ts` whose test isn't in the latest `last-run.json` results? | That spec's status is UNKNOWN, not green. Recommend `/qa-warden:run mode=smoke` (or `QA_RUN_OF_RECORD=1 npx playwright test` for the full suite) before trusting the picture. |
| **Stray / unmanaged spec** — any `tests/**/*.spec.ts` with no paired `specs/<base>.md`? | It is NOT `@smoke`-tagged, so a smoke run-of-record reads green while a full `npx playwright test` still runs it (a leftover throwaway can be a silent full-suite RED). `/qa-warden:run mode=smoke` and `/qa-warden:report` now warn on it; delete the stray spec (or pair it) and run `/qa-warden:doctor`. The mirror gap — an authored spec with **no** test — is named by `/qa-warden:coverage` (§1b). |

Use `Glob`/`Read` to check existence; mention what you found ("you have an app.context.md last verified <date> and 3 specs, but no tests yet → run `/qa-warden:gen`"). **When `bugs/*.md` is non-empty, lead the answer with the open defect(s) — they outrank a green last-run.**

---

# Knowledge map of the QA Warden plugin

**One-liner:** AI authors declarative specs → Playwright replays them deterministically nightly at **zero LLM cost** → AI triages **only on failure**. Shared UI flows live in an AI-maintained **page-object** layer, so a flow change is a one-file fix.

## Knowledge map (read on demand)

The command catalog, agent roster, capability-skill list, workflow order, mental model, and
safety rails live in **`${CLAUDE_PLUGIN_ROOT}/reference/knowledge-map.md`**. Read that file
before answering ANY of these — do not answer them from memory:

- "what commands are there" / "what does `/qa-warden:<x>` do" / any catalog or overview request
- "how do I <goal>" — it carries the workflow ORDER and each command's delegation target
- "what is <agent>" / "what is <skill>" — the agent + capability-skill rosters
- "why <x>" — the Mental model section (the load-bearing design rationale)
- anything about prod safety, `.env`, or what the toolkit refuses to do — Safety rails

The three sections above (How to answer, First 60 seconds, State read) are the behavioral
half and are always in context; the catalog is the reference half and is not. If a question
needs a fact you cannot see, the answer is to read that file, never to guess a command name.