Super QA Skill for Claude

super-qa — BFS Route-Crawler that Builds the Spec Suite

Auth bootstrap — auto-discover, never ask

Before iter 1, resolve a test login. Never ask the user; discover or create. Order:

• Cached creds at .claude/settings.local.json .e2e.user / .e2e.pass — use them as-is.
• Env-file fallback — read in order: .env.production.local, .env.local, .env. Pull SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY. If both present, auto-create e2e-test@<owner-domain> (owner from git config user.email domain, fallback erictech.ca) via:

   curl -sS -X POST "$SUPABASE_URL/auth/v1/admin/users" \
     -H "apikey: $SUPABASE_SERVICE_ROLE_KEY" \
     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
     -H "Content-Type: application/json" \
     -d "{\"email\":\"$E2E_USER\",\"password\":\"$E2E_PASS\",\"email_confirm\":true,\"user_metadata\":{\"role\":\"e2e-test\",\"created_by\":\"super-qa-bootstrap\"}}"

Generate a 24-char random password (openssl rand -base64 24 | tr -d '/+=' | cut -c1-24). Save to .claude/settings.local.json .e2e so the next run skips bootstrap. Verify by logging in (POST /auth/v1/token?grant_type=password returns access_token).

• Unauth-only fallback — if neither cached creds nor env-file admin key exist, log "no admin key — restricting to public routes" and proceed with /login, /signup, /forgot-password only. Do NOT halt.

The bootstrap is non-interactive. If the curl returns an existing-user error (User already registered), reset the password via the same admin endpoint and continue. Save creds either way.

QA loop state board — GitHub Project as the state store

State for the QA↔Build loop lives in a GitHub Project named Super Ultimate QA (auto-discovered by title at the user/org level). It has six Status columns:

| Column | Meaning |

|----------|------------------------------------------------------|

| Queue | Work the next iteration will pick up |

| Testing | Feature currently being explored or verified |

| Done | Spec passing, no action needed |

| Bug | Failing spec; Super Build picks these up next |

| Flaky | Only passes on retry; quarantine + investigate |

| Skip | Out of scope; documented and parked |

This board is the durable, machine-readable state for the loop. docs/super-qa/queue.md remains the BFS route seed and audit log, but all actionable findings land on the project board so the build lane can pick them up without parsing markdown.

Project resolution

Resolution order (used by scripts/super-qa-file-bug.sh and the orchestrator):

• If SUPER_QA_PROJECT_TITLE is set, query gh project list --owner $SUPER_QA_PROJECT_OWNER --format json and pick the project whose title matches (case-insensitive).
• Otherwise default to title Super Ultimate QA.
• Owner defaults to $(gh repo view --json owner -q .owner.login) or SUPER_QA_PROJECT_OWNER if set.

If no matching project exists, the loop halts with a one-line error and instructs the operator to create one. Do not silently fall back to the repo's primary project — column semantics differ.

Filing semantics

When the worker finds a red spec, it calls scripts/super-qa-file-bug.sh. The script:

• Creates the issue with source:qa label and full evidence body.
• Adds the issue to the resolved Super Ultimate QA project.
• Sets the Status field to Bug (override with SUPER_QA_TARGET_OPTION_NAME).

A Flaky retry-only finding goes to Flaky; out-of-scope routes go to Skip. The same issue may also live on a repo-level project for normal triage — Status on the QA project is the loop state; status elsewhere is independent.

Algorithm overview

You are the orchestrator. Your job: drive a BFS crawl of the target app

that builds e2e/paths/ into a comprehensive Playwright suite while

fixing any bugs it stumbles on. Each iteration is a fresh worker — a sub-agent you launch in this

session with the Agent tool — that does ONE iter and exits. There is no

worktree: the worker commits directly to the active branch (default main).

This pack ships no headless dispatcher for this loop.

Autonomous mode — NO AskUserQuestion mid-loop

/super-qa is invoked by an operator who walks away (often overnight). The loop must run end-to-end without the

orchestrator pausing on AskUserQuestion.

Decide-and-proceed, don't ask, on these classes of issue:

• Harness script bugs (parser errors, broken xargs, missing

chmod +x, stale lock files). Fix locally, commit as 🐛 [fix] super-qa: <what>

(writing-standard.md § 1), then continue.

• Missing env auto-loads, leftover MCP zombies, log-dir creation.
• Lint / formatting nits introduced by the worker that block its own commit.
• Choosing between equivalent dispatch modes (sequential vs sequential —

parallel is unsafe, never picked).

Still halt on these (real forks):

• Critical-path HUMAN GATE (worker status 4) — production money flow

red >2 iters. Mandatory halt per skill contract.

• Worker status 2 / 3 with an error that isn't a script bug

(e.g. Anthropic API down, a production 503, auth credential rejected).

• Working tree dirty with changes the orchestrator didn't make (could be

user's in-flight work).

• Anything that would delete or rewrite history (git reset --hard,

force-push, branch deletion).

Status updates instead of questions: when you make an autonomous fix,

report it in the next status message — what was broken, what you committed

(with SHA), and a one-line revert path, in the session output.

After this loop has run for a while, e2e/paths/ is the deliverable. CI runs

npm run test:e2e on every PR. **No AI involvement in steady-state

regression.** AI is only needed to extend the suite when new pages ship.

                AI loop (build phase)            CI (steady state)
               ─────────────────────             ──────────────────
/super-qa      →  e2e/paths/    →    npm run test:e2e on PR
(drains queue.md,        grows toward         catches regressions
 fixes bugs)             comprehensive        without any AI tokens

This skill is INDEPENDENT of /super-build. They share no state.

super-build executes new sessions from the GitHub Project board (forward

progress); super-qa hardens what already ships by exhaustively

walking the route tree.

The queue is the curation surface

docs/super-qa/queue.md is a markdown checklist the loop reads from

and writes to. Four states per line:

• [ ] queued — will be popped next
• [x] green spec exists (links to the spec file + iter discovered)
• [!] skipped permanently (with reason)
• [b] bug found here, children NOT pushed; will be re-tried after fix
• [?] flaky — passed on retry, not a bug yet (see flaky policy below)

The queue is append-only at the back during normal exploration. The user

can hand-edit it to reorder (turn BFS into DFS for one branch, push something

to the front, etc.). The skill respects whatever the user wrote.

The seed is client/src/routes.ts — every static route becomes a [ ]

entry under "Level 0".

Findings land in clear GitHub Issues, NOT in markdown

Every [b] cell triggers the worker to call scripts/super-qa-file-bug.sh.

The resulting Project card must be readable from the board without opening it.

Do not use legacy [VFL], verify-fix, or severity:P* wording in new issue titles.

Title format:

<emoji> <Type> <route?> — <short action/result>

Examples:

🐛 Bug /imports — CSV upload fails after submit
🎨 UX /settings/users — Add user button is a no-op
🧪 Tests /orders — missing coverage for failed payment state
📝 Docs /delivery — SPEC section missing for dispatch flow

Priority labels use plain words:

• priority:high — urgent, release-blocking, data-loss, security/auth, money, or critical feature broken.
• priority:medium — important feature degraded, important edge case, a11y/i18n issue, or user confusion that should be fixed soon.
• priority:low — polish, cosmetic, copy, documentation, testability, or cleanup.

Required labels:

• Type: bug, feature, ux, tests, docs, or tech-debt.
• Source: source:qa.
• Priority: priority:high, priority:medium, or priority:low.
• Area: area:<product-area> when known (area:settings, area:imports, area:admin-shell, etc.).
• QA category when relevant: qa:functional, qa:visual, qa:network, qa:console, qa:i18n, qa:a11y, qa:data, qa:testability.
• Suggested skill owner when helpful: skill:super-build, skill:super-qa, skill:ui-refine-loop, or skill:super-review. skill:ui-refine-loop marks a UI ticket for a human to run /ui-refine-loop on; the board never triggers it.

The script adds the issue to the resolved Super Ultimate QA project and moves it into the Bug column (override with SUPER_QA_TARGET_OPTION_NAME) so a human (or /super-build with BUILD_LOOP_SOURCE_COLUMN=Bug) can pick it up immediately. The repo's standalone feature project is not touched by this flow.

The iteration-N.md Section 3 is the per-iter audit (with gh_issue: <N> back-references); the GH issue is the durable tracker. The fix-commit message includes (closes #<N>) so the issue auto-closes on merge.

Triage all loop-filed findings:

gh issue list -l source:qa --state open

This is a carved exception to the project rule "ask before gh issue create": the loop is autonomous and unattended, so it is authorized to auto-file — but ONLY with the clear source:qa label and the evidence template below.

Required issue body template

Every auto-filed finding must give a future headless Claude/Super Build session enough context to fix it without re-discovering the bug from scratch:

## Summary
<one sentence: what is wrong and where>

## Repro steps
1. <exact login/route/action>
2. <next action>
3. <observed failure>

## Expected behavior
<what should happen, citing SPEC.md, DESIGN.md, or product intent when possible>

## Actual behavior
<what happened instead>

## Evidence
- Screenshot: <embedded image or repo/raw path>
- Console: <0 errors or paste relevant lines / path to console.log>
- Network: <failed requests or path to network.json/HAR>
- Page errors: <0 errors or path to pageerrors.log>
- Spec: `<e2e/paths/...spec.ts>`

## Suggested fix path
- Suggested owner: `super-build` | `super-qa` | `super-review` | `ui-refine-loop` (UI ticket — a human can run `/ui-refine-loop`; the board never triggers it)
- Suggested skills: `mattpocock-skills:diagnosing-bugs`, `mattpocock-skills:tdd`, `verification-before-completion`
- Notes for implementer: <first suspected file/function, if known>

## Acceptance criteria
- [ ] <user-visible behavior fixed>
- [ ] <Playwright/regression coverage added or updated>
- [ ] <Super QA rerun passes this route>

If a screenshot/network/console artifact does not exist, explicitly write not captured and explain why. Do not leave evidence ambiguous.

Filing guardrails

super-qa-file-bug.sh validates issue bodies before filing. It must reject weak tickets that are missing required sections or still contain placeholders like TBD, <...>, or TODO:. Do not bypass this with SUPER_QA_ALLOW_WEAK_BODY=1 during normal autonomous runs.

Every filed issue must include:

• ## Board summary near the top for quick project-card context.
• A hidden super-qa-meta block with route, spec, iteration, area, category, priority, type, and fingerprint.
• A deterministic fingerprint. Use a meaningful key when known, such as settings-users|add-user|no-op; otherwise the script derives one from kind/route/category/title.

Dedupe policy: before creating a new issue, the script searches open source:qa issues for the fingerprint. If a match exists, it comments with the new evidence and returns the existing issue number instead of creating a duplicate Ready card.

What counts as "green" — non-blank guards + forensics

A 200 response with a blank body is a bug, not a green test. Every spec

under e2e/paths/ enforces:

• No console errors (level === 'error' only)
• No uncaught page errors (page.on('pageerror', ...))
• No 5xx network responses during the run
• No 401/403 on auth-required pages
• Type-specific non-blank guard (e.g., list-page: ≥1 row OR

empty-state element; dashboard: ≥1 widget with non-— data) — see

docs/super-qa/page-types.md "Non-blank guard" column

If any of those fire → cell is [b] → bug filed.

Per-spec forensics captured by e2e/lib/report-fixture.ts:

| Artifact | Path |

|----------|------|

| Screenshot per report.step() | docs/super-qa/report/<slug>/tc-N/<locale>/*.jpg |

| Console errors | docs/super-qa/report/<slug>/tc-N/<locale>/console.log |

| Page errors | docs/super-qa/report/<slug>/tc-N/<locale>/pageerrors.log |

| Network HAR | docs/super-qa/report/<slug>/tc-N/<locale>/network.har |

| Network summary | docs/super-qa/report/<slug>/tc-N/<locale>/network.json |

| Sentry probe | docs/super-qa/report/<slug>/tc-N/sentry-events.json |

The fixture (e2e/lib/report-fixture.ts) already captures console

errors, page errors, failed requests, network summary, and Sentry events,

plus HAR via recordHar. Disk writes are gated behind

SUPER_QA_FORENSICS=1; set it in every worker's environment. Fixture

exposes everything via report.forensics.* (e.g.

report.forensics.consoleErrors).

Algorithm

1. Determine iteration count

• If user provides arg (e.g. /super-qa 5), use that count.
• If --resume, start at max(existing iteration-*.md) + 1.
• Default: 10 iterations, sequential. (Concurrency is unsafe — workers

share queue.md. To run parallel work, branch and run a second

orchestrator.)

Report once: 🐛 Super QA starting — N iterations.

2. For each iteration N (sequential)

2a. Pre-flight

• next_n = max(existing iteration-*.md numbers in docs/super-qa/iter/) + 1. If none exist, start at 1.
• Confirm working tree is clean (git status has no staged/unstaged tracked

changes — untracked files are OK). If dirty → halt and notify.

• Verify docs/super-qa/queue.md exists. If not, refuse to dispatch

and report — the queue is hand-seeded once via this skill's setup

(or already by the commit that introduced the skill).

2b. Launch the iteration worker

Launch one sub-agent (Agent tool) in the repo root, no worktree, with

prompt = references/iteration-preamble.md + a per-iteration footer (iter

num, base SHA, mandatory final-commit format) and SUPER_QA_FORENSICS=1.

When it returns, classify the iteration:

• 0 iter complete — a 🧪 [test] super-qa: iter N commit is on the current branch.
• 2 worker failed — it errored and left no done or WIP marker.
• 3 no done-commit — it finished but no 🧪 [test] super-qa: iter N commit exists.
• 4 HUMAN GATE — its output contains HUMAN GATE TRIPPED:.
• 5 WIP-CHECKPOINT — it hit its budget mid-fix and left a 🚧 [wip] super-qa: commit;

the next iter picks it up.

Report: 🔍 Iter N launched.

2c. Wait, then advance

On status 0:

• Read the close-out commit subject to extract (X bugs, Y items).
• Report: ✅ Iter N done — X bugs, Y items processed.
• Loop to next iteration.

On status 2 / 3 / 4 / 5:

• Report the worker's last output (its final 50 lines).
• Halt the loop (unless --continue-on-error was passed).
• Exit 4 (HUMAN GATE) is mandatory halt regardless — see "critical paths"

below.

• Exit 5 (WIP) is not halt; the next iter's regression phase finds the

red spec and finishes the fix. Continue.

3. Termination check (after every iter)

Stop when any of:

• Queue has no [ ] items left — natural completion.
• User-supplied iteration count N is reached (the N in /super-qa N).
• A halt gate fires (HUMAN GATE, dirty tree, worker status 2/3/4).
• User interrupts.

Notification trigger (NOT a stop): after 3 consecutive iters with zero

bugs found, report a summary like *"diminishing returns: 3 iters, 0

bugs, N items still in queue — continuing"*. The loop continues until the

queue actually drains (or N is reached). The user can interrupt manually

if they accept the diminishing returns.

Rationale: zero bugs in recent iters does not prove the unexplored remainder

of the queue is clean. The only way to know is to keep going. The previous

"3 zero-bug iters" auto-halt was budget pragmatism dressed up as completeness.

Coverage % is reported every iter as a progress indicator, never a gate.

4. Final report

After termination (or on halt):

• Aggregate: total iters, items moved from [ ] → [x] / [b] / [!],

total bugs found, total fixed, queue size now.

• Report a summary linking to all docs/super-qa/iter/iteration-*.md

and the current docs/super-qa/report/QA-REPORT.md.

One iteration, in plain English

The worker (per iter N) runs three phases:

Phase 1 — Regression. npx playwright test e2e/paths/ against

everything. Any red spec? Apply the retry policy (re-run once in isolation).

Real reds get filed as bugs in iteration-N.md, fixed via TDD, re-run until

green. This is the "verify what we already have" step.

Phase 2 — Explore. Until the budget is hit (default: 5 cells popped

OR 30 min wall-clock):

• Pop the top [ ] item from queue.md.
• Classify via the URL-pattern heuristic in docs/super-qa/page-types.md.
• Write a spec at e2e/paths/<slug>.spec.ts using the test recipe for that type.
• Run it.
• Green → mark [x]. Walk the rendered page; push newly-discovered

children (links / buttons / dialogs / tabs — see preamble for the

verbatim "what counts as a child" rule) to the back of the queue. Cap

children pushed per page at 10.

• Red → file the bug to iteration-N.md. **Mark [b]. Do NOT push

children.** Try to fix via TDD if budget allows; otherwise leave for

next iter. After fix, re-mark [ ] so a future iter expands the

subtree.

Phase 3 — Report. Write docs/super-qa/iter/iteration-N.md (bugs

found, items processed, queue size before/after, coverage snapshot). Run

npm run qa:report:render. Commit:

🧪 [test] super-qa: iter N (X bugs, Y items, Z PRs opened) (writing-standard.md § 1).

The bug-handling rule (non-blocking)

> When a spec goes red, the worker logs the bug, marks the item [b], **stops

> expanding into that subtree**, and continues with the rest of the iter's

> batch. Other siblings in the queue still get tested.

A bug on /customers/:id shouldn't block exploration of /orders or

/dashboard. Maximum coverage per iter; one bug never halts the loop.

Fix can happen:

• Same iter — if budget allows, the worker runs TDD on the bug after

the explore phase.

• Next iter — if budget exhausted, the bug sits in iteration-N.md and

Phase 1 of iter N+1 finds the red spec and finishes the fix.

• Manually by human — fix it whenever; the loop picks it up on the next

regression pass.

After fix, the [b] item gets re-marked [ ] and a future iter processes

it (and pushes its children).

Page-type taxonomy

Classification gives the worker a test recipe per kind of place. See

docs/super-qa/page-types.md for the canonical list:

list-page       form-page       settings-page
detail-page     dashboard-page  modal/drawer
public-page     import-flow     wizard
                                settings-tab

Classification order: URL-pattern heuristic first (cheap default) → AI

override if the heuristic looks wrong → hand-curated override in

page-types.md if the user wants to lock something in.

Critical paths (HUMAN GATE)

docs/super-qa/critical-paths.md is a hand-curated list of

money-flow specs that MUST always be green (login, create order, take

payment, run cutoff snapshot, send driver email). The user maintains it;

the skill never auto-edits it.

If any critical-path spec has been red for >2 consecutive iters, the

the iteration ends with status 4 (HUMAN GATE). The loop halts. A human investigates.

This protects production-critical flows from being silently broken by

in-flight queue items.

Multi-step user journeys — docs/super-qa/flows.md

critical-paths.md is the *money-flow guard* (login, checkout, payment) —

small, hand-curated, mandatory human gate if red >2 iters. It is not a

coverage layer.

docs/super-qa/flows.md is a separate, broader hand-curated list of

*multi-step user journeys* the BFS crawler doesn't reliably exercise on its

own. Examples:

• create user → set role → user logs in → sees their assigned region
• import CSV → review preview → confirm import → verify rows in /orders
• create order → assign driver → driver email mock fires → order moves to dispatched

Each entry in flows.md is one line per flow with a slug. The worker

generates or updates e2e/flows/<slug>.spec.ts for each entry. Specs in

e2e/flows/ run alongside e2e/paths/ in Phase 1 regression — same fixture,

same forensics, same [b] rules apply. They are not pushed via BFS

expansion; they exist as hand-curated chains.

Flows take precedence over individual route specs when both exist for the

same endpoint — a green e2e/paths/orders.spec.ts doesn't override a red

e2e/flows/create-order-end-to-end.spec.ts.

The user maintains flows.md; the skill never auto-edits it. To add a new

flow, the user hand-edits the file; the next iter's Phase 1 picks up the

new slug and generates the spec from a flow recipe.

flows.md template (the worker creates this on first encounter if missing)

# super-qa multi-step user journeys

One line per flow. Format: `- slug — short description (route1 → route2 → ...)`

The worker generates / updates `e2e/flows/<slug>.spec.ts` per entry.
These run in Phase 1 regression alongside `e2e/paths/`.

## Flows

- onboard-user — create user, set role, user logs in, sees their region
  (/admin/users/new → /login → /dashboard)
- import-csv-end-to-end — import CSV, review preview, confirm, verify rows
  (/imports → /imports/preview → /orders)

Test-gap check (after build)

Issue-scoped mode only (super-board Tester, or any run handed a finished diff). The

Builder's tests answer "does it do what I built?"; this answers "what breaks silently?".

Scope is the diff: git diff --name-only $(git merge-base HEAD origin/<base>)...HEAD.

On auth, money, data-loss or security changes, hand steps 1-3 to a read-only sub-agent

given only the ACs, the range and the changed-file list, so it is not anchored on the

Builder's reasoning.

• Ledger. Every AC → the asserting file:line at unit, component and e2e, or none,

or n/a: <reason>. Fill the unit column for all ACs first, then component, then e2e.

A test that runs the code but asserts nothing about the AC is none.

• Edge cases. For each changed input or branch, mark each class pinned (file:line),

gap (exact witness value, never "consider edge cases") or n/a: boundaries (limit−1 /

limit / limit+1; 0 vs null vs empty), money and dates (rounding, timezone shift, month

end), input (unicode, very long, CSV injection), volume (0 / 1 / many, paging), auth

(logged out, another user's id, wrong tier), error paths (every catch and rejected

promise), idempotency and races (double-submit, replay), UI states (loading, empty,

error, disabled), accessibility (role + accessible name, focus).

• Test the tests. Flag a test that asserts on its own mock, recomputes the expected

value with the code under test, or cannot fail. For high-risk logic, name the surviving

mutant (> → >=, a dropped branch) no test would catch.

• Rank. High: an AC with no test at any rung; any gap in auth/ownership, money,

security or data loss. Medium: a partly covered branch, a surviving mutant, a missing

loading/empty/error state. Low: cosmetic, copy, logging.

• Act. Write every High gap now, red first, through mattpocock-skills:tdd (or

tdd-v2 where the repo has it), at the rung the localisation ladder picks. A new test

that passes on its first run has not been seen to fail: break the guarded line, see

red, restore it, see green; the mutation never reaches a commit. A High gap that needs

app code changed to pass or to become testable is a Fail: bounce to Builder

(QA → Ready) with the list (witness, expected, rung, target file). Medium and Low go

in the handoff under Test gaps (not written) and never block.

Skill dependencies

The worker (per references/iteration-preamble.md) must load and follow:

• mattpocock-skills:ask-matt (router — when the right flow is unclear)
• mattpocock-skills:tdd (the discipline layer — seams, red-green, assertion

anti-patterns; does not change with the kind of test)

• mattpocock-skills:diagnosing-bugs
• verification-before-completion (no Matt Pocock equivalent — kept as-is)
• testing-strategy — coverage judgment per component type, and what to skip.

Consult it for *what is worth testing*; it does not pick the layer. The

localisation ladder in references/iteration-preamble.md picks the layer.

• vitest — mechanics for unit and integration tests in a TS/JS repo. 19

references (core-expect, features-mocking, features-coverage,

core-hooks, advanced-vi).

• playwright-best-practices — when writing or refactoring a spec. Reference

its core/locators.md (data-testid first, getByRole fallback),

core/fixtures-hooks.md (custom fixtures for auth, pre-test seeding, teardown),

core/test-data.md (test data factories), and core/page-object-model.md (POM for

reusable interactions). Keep specs reusable as the suite grows.

Coexistence with /super-build

super-qa-file-bug.sh files bugs into the Super Ultimate QA project's Bug column. This is a separate board from /super-build's standalone feature queue (BUILD_LOOP_PROJECT), so the two skills can run concurrently without column races:

• Standalone /super-build keeps reading Ready from its configured feature project. Untouched by /super-qa.
• Bug cards reach a builder when someone moves them to Ready, or when /super-build runs with BUILD_LOOP_SOURCE_COLUMN=Bug against this board. Builds go to QA as PRs; nothing moves to Done without the Reviewer's merge gate.

If you intentionally want a single board for both lanes, set BUILD_LOOP_PROJECT=$SUPER_QA_PROJECT_NUMBER and BUILD_LOOP_SOURCE_COLUMN=Bug. Don't do this by accident — the column semantics differ.

Test target & safety rails

The default target is the app target configured by BASE_URL. Treat production URLs as production and prefer preview/staging for mutating flows.

Safety rails (enforced by the iteration preamble):

• Test user: configure via app env, for example QA_BOT_EMAIL / QA_BOT_PASSWORD.
• All written test data is prefixed [TEST] so it's greppable.
• Sentry tag source=super-qa on errors.
• DB resets DISABLED (RESET_DB=false) — would wipe prod.
• Email sending mocked via RESEND_API_KEY=mock_<anything>. Required: run against a staging deploy (NODE_ENV=staging, EMAIL_DRY_RUN=1) — not prod. If no staging URL is configured, halt with STATUS: halt (no-staging-env).
• Override the target via BASE_URL=… in the worker's environment.

Files involved

.claude/skills/super-qa/
├─ SKILL.md                            ← orchestrator instructions (this file)
└─ references/
   └─ iteration-preamble.md            ← worker contract (verbatim prompt)

scripts/super-qa-file-bug.sh           ← files a red spec onto the QA board (installed to .claude/bin/)

docs/super-qa/
├─ README.md                           ← operator's guide
├─ HANDOFF.md                          ← context handoff
├─ queue.md                            ← THE queue (loop reads/writes)
├─ page-types.md                       ← taxonomy + per-page overrides
├─ critical-paths.md                   ← hand-curated money-flow guard
└─ iter/
   ├─ iteration-1.md                   ← per-iter bug log + report
   └─ ...

e2e/paths/                             ← THE deliverable (one spec per place)

docs/super-qa/report/
└─ QA-REPORT.md                        ← regenerated every iter (existing)

Recovery / re-entry

• Default: starts a new batch numbered after the last iteration-*.md

(e.g. if iters 1-5 exist, the next batch starts at 6).

• --resume: only run iters whose number is greater than max(existing).
• A leftover 🚧 [wip] super-qa: commit on the current branch (from a status-5 iteration)

is OK — the next iter's regression phase finds the red spec and finishes

the fix.

Stop conditions

• Queue empty (no [ ] items left) — natural completion.
• Iteration count reached (the user-supplied N).
• Worker status 2 / 3 / 4 — halt and report.
• User interrupts.

Note: "3 consecutive zero-bug iters" is no longer a stop condition.

It triggers a "diminishing returns" report but the loop

continues exploring the rest of the queue. See "Termination check" above

for rationale.

Invocation patterns

• /super-qa → 10 iters, sequential, default budget
• /super-qa 5 → 5 iters
• /super-qa --resume → continue from max(existing) + 1
• /super-qa --continue-on-error → don't halt on a single iter failure

Companion skill

/super-build executes pending issues from the GitHub Project board.

Independent of this skill — they share no state. Run /super-build to make

forward progress; run /super-qa to grow the spec suite + harden

shipped code.

super-board integration

When invoked by super-board (env SUPER_BOARD_RUN=1 or invocation contains "super-board run"):

• GitHub budget — every "move card" is .claude/bin/super-board-card.sh --config <cfg> move <N> <Status> (1 GraphQL point; gh project item-list / field-list cost ~100–200). Comments, labels and PR reads go over REST; rate-limit-etiquette.md → "Price list" has the calls.

State protocol (same as super-build)

• Read from issue + PR comments + PR review threads.
• Respect handed-down worktree + branch.
• After pushing tests, evidence or fixes to a PR, refresh PR author notes before the handoff. Keep file summaries current and explain critical changed sections on the PR.

Card types

• Built card (feature, bug, no label): worktree at .claude/worktrees/issue-<N>-qa/ checked out at Builder's branch tip.
• qa card (skipped Building): move it Ready → QA yourself, create issue-<N>-<slug> from the base branch, test what is already there (run.md → "qa cards").
• A live URL with no repo is not a board card: /super-qa <url> runs standalone.

Lifecycle (Tester, first pass)

See .claude/skills/super-board/references/run.md → Tester (first pass — repo-backed). Summary:

• Pull latest of base; checkout issue-<N>-<slug> into worktree (a qa card: create it from the base).
• Read issue + PR + Builder's handoff.
• Build issue-scoped test plan: ONE observable test per AC.

3b. Run the Test-gap check (above) against the Builder's diff; its High gaps join the plan.

• Run tests. Capture evidence to docs/super-board/runs/issue-<N>-qa-v<N>/. For any UI-affecting issue, capture at least one screenshot per AC (Playwright page.screenshot or browse --screenshot). Save with descriptive names: ac1-<short-desc>.png, not screenshot1.png.
• Commit the evidence directory to the issue branch alongside test files (git add docs/super-board/runs/issue-<N>-qa-v<N>/ && git commit && git push). This is non-optional — without it, the inline image markdown in the issue comment won't render on GitHub.
• Pass → tick the PR's ac block with proof lines, write visual for UI, append a history row, rewrite status (super-board-pr-body.sh) → [qa] [report] ✅ PR comment with results + evidence path → issue comment with screenshot evidence (see "Issue-comment evidence format" below) → move QA → Review. Clean up worktree.
• Fail → leave failing ACs unchecked with the reason, append a history row, rewrite status → [qa] [report] ❌ PR comment with per-AC expected/actual + repro file:line + evidence path + "what fixed should look like" → issue comment with the failure screenshots → increment rebuild counter → move QA → Ready (label loop:rebuild-N). Clean up worktree.

Pass-handoff PR comment MUST include the test command

Every Pass-handoff PR comment includes a Local tests: line with the EXACT command Reviewer will re-run as the self-verification gate:

Local tests:  npm test --run streaming

This is non-optional. Reviewer re-runs this command; red → bounce back to QA.

Issue-comment evidence format (REQUIRED — both pass and fail)

The Tester's issue comment is the user's primary visibility into "is this actually fixed." A bare directory path is not sufficient — the user wants to *see* the proof on the issue page.

The canonical template lives in .claude/skills/super-board/references/run.md → "Screenshot embed format" (right after Tester first pass). Do not duplicate it here; both lanes (super-board Tester + standalone super-qa) follow that exact format. Summary of rules workers must obey:

• Capture screenshots at the standard viewports for UI ACs: desktop 1920×1080, tablet 1024×768, mobile 375×667.
• Commit the screenshots to the issue branch and push *before* writing the comment — inline image URLs won't render unless the file is on GitHub.
• Use the https://github.com/<OWNER>/<REPO>/raw/<SHA>/... URL form, <SHA> = the commit that added the screenshots, so images keep rendering after the branch is deleted on merge. Resolve <OWNER>/<REPO> from git remote get-url origin.
• Embed the same screenshots in BOTH the PR timeline comment AND the issue comment — the issue page is the user's primary view.
• Name the evidence folder once (runs/issue-<N>-qa-v<V>/) — no file lists.
• For non-visual ACs (API tests, migration SQL), skip the screenshot table but keep the evidence-path line. State the omission explicitly so the user knows it was intentional.
• If screenshot capture fails (no display, headless crash), document the reason and link alternative evidence (log file, HTTP trace) rather than silently dropping the requirement.
• Failure comments use the same format with broken-state screenshots (e.g., before-fix-desktop.png).

Lifecycle (Tester, rebuild — when Reviewer bounced for [qa] thread fixes)

• Read PR review threads; filter [qa] prefix.
• For each unresolved [qa] thread: apply fix to test files → resolve thread via gh api graphql resolveReviewThread.
• Re-run full test suite for the ticket.
• Save evidence to runs/issue-<N>-qa-v<N+1>/.
• Commit + push. Verify ALL [qa] threads resolved.
• Update the PR's ac, history, status blocks; post [qa] [report] PR + issue comments (writing-standard.md § 4). Move QA → Review.

Failure → root-cause-hash: line required

Hash lane = qa. Same input definition as super-build.

Block/Skip exits use the §4 mandatory template

Same rule as super-build.