# QA Deck repo setup — agent prompt

Paste this whole file into your AI coding agent (Claude Code, Cursor, etc.) at the
root of the product repo you want to test with QA Deck. It instruments the repo so
QA Deck can generate route-aware checklists from it and anchor findings to your UI.

---

You are setting up this repository for **QA Deck**, a manual-QA service that shows
testers a per-page checklist inside the running app and captures findings anchored
to specific UI elements. QA Deck generates its checklists from **scenario specs in
this repo** — the repo stays the single source of truth for what should be tested.

Work through the tasks below in order. Keep every diff reviewable, do not change any
runtime behavior except where a task explicitly says so, and follow this repo's
existing conventions for naming and formatting.

## Task 1 — Create `specs/README.md` and the spec format

Create a `specs/` directory with a `README.md` documenting the format below, then
author scenario specs (Task 2) that follow it.

```markdown
### N. Group title

**Surface:** /route?view=subview <!-- optional, see rules below -->

#### N.M Scenario name

**Steps:**

1. Intent-level action (what a tester does, not which selector they click)
2. ...

**Expected:**

- Observable outcome
- ...

**Hidden state checks:** <!-- optional -->

- DB/queue/log effect a tester cannot see but an agent can verify
```

Format rules:

- One `####` heading = one checklist item. `###` groups related scenarios.
- Steps are **intent-level** ("Submit the form with an invalid email"), never
  selector-level ("Click `#btn-2`"). Selectors change; intent does not.
- `**Surface:**` pins a group (or a single scenario, which overrides its group) to
  a route — including a sub-view like `/documents?tab=estimates`. Omit it only when
  the flow genuinely spans several pages. Scenarios QA Deck cannot place from a
  Surface pin or a route path written in the steps fall back to a global bucket
  shown on every page — pins are what make checklists land on the right screen.
- Multiple surfaces: one comma-separated line (`**Surface:** /a, /b`). A second
  `**Surface:**` line replaces the first.
- Write specs in English.

## Task 2 — Author initial scenario specs

Identify the 5–10 most important user flows in this product (authentication,
onboarding, the core object's create/edit/delete, payment or other irreversible
actions, permission boundaries). For each, write a spec file in `specs/` using the
format above. Ground every scenario in what the code actually does — read the
relevant routes and components first; do not invent behavior. Give every group or
scenario a `**Surface:**` pin whenever the flow lives on one page.

## Task 3 — Add `data-ref` anchors to interactive elements

Add a `data-ref="<area>-<element>"` attribute (e.g. `data-ref="invoice-form-submit"`)
to interactive and landmark elements: buttons, links, form fields, table rows, empty
states, dialogs.

- Values must be **stable across refactors** — name them after what the element
  _is_, not where it sits or how it's styled.
- Values do not need to be globally unique; repeated components may share one.
- Do not change any behavior — attributes only.
- If this repo already has a test-id convention (`data-testid`, `data-test`), keep
  it and add `data-ref` alongside; QA Deck anchors on `data-ref`.

These anchors let QA Deck pin a finding to the exact element a tester picked, and
double as robust selectors if you later generate end-to-end tests from these specs.

## Task 4 — Embed the widget, gated to non-production

Add the QA Deck widget script to the app shell, rendered **only when an environment
variable is set** — the variable is the entire off-switch and must never be set in
production. For a Next.js app:

```tsx
{
  process.env.NEXT_PUBLIC_QA_DECK_URL ? (
    <script
      src={`${process.env.NEXT_PUBLIC_QA_DECK_URL}/qa-widget.js`}
      data-qa-deck-url={process.env.NEXT_PUBLIC_QA_DECK_URL}
      defer
    />
  ) : null;
}
```

Adapt the pattern to this repo's framework. Document in the repo's env example file
that the variable is set on dev/staging only. If the app sends a Content-Security-
Policy, extend `script-src` and `connect-src` with the QA Deck origin **only in the
non-production configuration**.

## Task 5 — Sync checklists from CI

Add a CI step on merges to the default branch that pushes regenerated checklists to
QA Deck, using a repository secret for the token:

```yaml
- name: Sync QA Deck checklists
  run: npx qadeck-sync
  env:
    QADECK_TOKEN: ${{ secrets.QADECK_TOKEN }}
```

If the `qadeck-sync` CLI is not yet available on your plan, note in the PR that
specs are uploaded manually from the QA Deck project settings page instead, and
leave the CI step commented out with a TODO.

## Task 6 (optional) — Staging testability audit

Report (do not fix unprompted): whether staging has seeded data and dedicated test
accounts that make deep, stateful flows reachable; and whether the browser console
is clean on the main pages — QA Deck attaches a console tail to every finding, so
pre-existing noise degrades triage.

## Done criteria

- `specs/README.md` documents the format; initial specs cover the core flows, each
  pinned with `**Surface:**` where applicable.
- Interactive elements across those flows carry stable `data-ref` attributes.
- The widget embed exists, renders only when the env var is set, and the env
  example documents it.
- The CI sync step exists (or is stubbed with a TODO per Task 5).
- A short summary lists every file touched and every flow covered by a spec.