qa-audit

name	qa-audit
description	Full QA audit orchestrator. Use when the user asks to "test my app", "run a full QA audit", "test everything", or invokes /qa-audit. Discovers what kind of application this is, selects the relevant QA agents (ui-inspector, api-sentinel, security-scout, perf-guardian, data-validator, regression-watcher), runs them, and merges their reports into one master QA report.

QA Audit Orchestrator

You are coordinating a team of specialized QA agents. You do the discovery and the final merge yourself; the agents do the testing.

Step 1 — Understand the application (yourself, before any agent)

First: check for qa-reports/qa-profile.md. If it exists, read it — it's the toolkit's accumulated memory of this project (how to run it, critical flows, quirks from previous runs, known non-issues). Trust it but spot-check the run commands still work. If it does NOT exist, run the qa-init skill flow first (study project, write profile) — every future run gets faster because of it.

Beyond the profile, confirm the current picture:

• Read README.md, package.json / pyproject.toml / go.mod, top-level directory structure.
• Identify: app type (web frontend / API / fullstack / CLI), framework, database (if any), test suite (if any), how to run it locally.
• Determine what is testable right now: Can a dev server start? Is there a deployed URL the user owns? Is there a database with data?
• Check "Known Non-Issues" in the profile: findings the user already dismissed must not be re-reported (mention them in one line at most).

If you cannot determine how to run the app, ask the user ONE consolidated question (run command + URL + test credentials if auth exists) before starting.

Black-box mode: if the user only has a URL and no codebase, the white-box agents don't apply. Use web-auditor (passive HTTP checks) plus ui-inspector (if Playwright MCP is available and the site is the user's own or testing is clearly harmless: no form submissions, no load). State the limitation in the final report.

Step 2 — Select agents

Condition	Agent
Has web UI + Playwright MCP available	ui-inspector
Has HTTP API endpoints	api-sentinel
Always (white-box security review works on any code)	security-scout
User asked about performance OR app has API/DB	perf-guardian
Has database or data files	data-validator
There is a recent diff/PR/branch to compare	regression-watcher
URL only, no codebase (black-box)	web-auditor (+ ui-inspector if browser available)

Degraded-tool fallback: if Playwright MCP is not available, don't skip the audit — run web-auditor for the passive checks, list the browser-dependent items under "Pending", and tell the user how to enable browser testing.

Tell the user which agents you selected and why (2–3 lines), then proceed — don't wait for confirmation unless something is destructive or targets a non-local URL.

Auth gate (if the app has an active login): before launching agents, resolve credentials per .claude/agents/_auth-protocol.md. The login's own security is always tested (no creds needed). To cover pages BEHIND the login: check profile/env for test creds and programmatic bypass; if none and the login is blocked by CAPTCHA/SSO or just has no test account, ask the user once — provide a throwaway test account to continue, or skip the authenticated area (reported honestly as "not tested"). If the user provides credentials, log in once, save gitignored storageState, and pass that to the agents. Never persist the password; never solve a CAPTCHA.

Step 3 — Prepare shared context

Create a timestamped run folder: qa-reports/runs/<YYYY-MM-DD_HHMM>/ (use the current date/time). All reports from this audit go inside it — this is what enables /qa-trend to compare runs over time.

Write <run-folder>/audit-context.md containing: app type, framework, how to start the app, base URL, test credentials location, and anything agents must NOT touch. Every agent prompt must tell the agent to read this file first and write its report inside this run folder.

Step 4 — Launch agents

• Instrument before launching: if you start the dev server, tee its stdout/stderr to <run-folder>/server.log. Tell every agent the log path. This is what turns surface findings into root-cause findings: when ui-inspector sees a UI error, it greps server.log for the stack trace that fired at that moment; when api-sentinel gets a 500, the server log says why. A finding that correlates UI symptom + network call + server exception is worth ten findings that just say "the button doesn't work".
• Launch independent agents IN PARALLEL (single message, multiple Task calls).
• Exceptions to parallelism:
  • perf-guardian runs AFTER ui-inspector/api-sentinel finish (load tests would distort their timings and stability).
  • Agents sharing one dev server: start the server yourself first so they don't each try to start it.
• Each agent writes its own report to <run-folder>/<agent>-report.md and returns only a verdict + top findings (their handoff contract).

Step 5 — Merge into master report

Read all <run-folder>/*-report.md files and write <run-folder>/QA-MASTER-REPORT.md:

# QA Master Report — [app] — [date]
## Executive Summary
[3–5 sentences: overall health, ship/no-ship recommendation]
## Verdict Board
| Area | Agent | Verdict | Critical | High |
|------|-------|---------|----------|------|
## Top Issues (cross-agent, deduplicated, by severity)
1. [CRITICAL] [title] — found by [agent(s)] — [one-line impact] — [report link]
## Cross-Agent Correlations
[e.g. "slow endpoint found by perf-guardian is the same one failing validation
in api-sentinel" — connecting findings is YOUR job, agents can't see each other]
## Recommended Fix Order
1. [issue] — [why first]

Deduplicate: if two agents found the same root cause, merge into one issue listing both sources.

Then generate <run-folder>/QA-MASTER-REPORT.html using the template at report-template.html (in this skill's folder). Fill every {{PLACEHOLDER}}, repeat the marked FINDING / POSITIVE / AGENT_ROW blocks per item, order findings by severity with CRITICAL/HIGH expanded (open attribute) and the rest collapsed. Keep it a single self-contained file — it's the shareable deliverable (works in any browser, print-to-PDF ready).

Finally, copy both master reports to qa-reports/QA-MASTER-REPORT.md and qa-reports/QA-MASTER-REPORT.html (the "latest" convenience copies), and mention that /qa-trend can compare this run against previous ones.

Step 5.5 — Materialize tests from the audit

If the run produced discovered-flows.json or discovered-endpoints.json (and the project is a codebase, not URL-only): launch test-architect in audit-driven mode, pointing it at this run folder. It converts explored flows into permanent Playwright specs under tests/e2e/ and every reproducible finding into a regression test under tests/e2e/regressions/ — the audit's knowledge becomes a re-runnable suite instead of evaporating.

Skip (and just mention the option) only if the user asked for "audit only" or the project already has extensive E2E coverage of the same flows.

Step 6 — Feed the memory (learning loop)

Update qa-reports/qa-profile.md:

• Append to Quirks & Learnings: anything that will make the next run smarter — startup time observed, flaky areas, auth gotchas, slow endpoints, selectors that needed special handling, tools that weren't available. Dated, one line each. Prune entries that are no longer true.
• If the user dismisses a finding during this session ("that's intentional", "won't fix"), move it to Known Non-Issues with the reason.
• Update the profile's "Updated" date.

This is what makes the toolkit a resident tester instead of a tourist: run N makes run N+1 faster and quieter.

Step 7 — Final response to user

• Ship/no-ship verdict + severity counts.
• Top 3 issues in plain language.
• Paths to the HTML master report, markdown master report, and individual reports.
• Tests generated (count + location), if Step 5.5 ran.
• Offer: "want me to fix the critical issues?"