audit-product

name	audit-product
description	Drive the whole running product through the spec's user flows end to end and, since it is already in the real UI, check the accessibility target on the same journeys. Use in the release phase (run by release-product) or standalone once features are built. It proves the cross-feature integration a per-task verifier could not see — state carried across steps, the seams between features, success and error states — then re-walks the core journeys with an automated axe pass plus what automation misses (keyboard operability, focus order, screen-reader semantics, contrast, reduced motion, form errors).
argument-hint	[--reaudit]
hooks	{"PreToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/scripts/guard-write-scope.sh '*/.dev-skills/*' '*/.dev-skills/build-plan/*' '/tmp/*' '/private/tmp/*' '/var/folders/*'"}]}]}

Audit Product Skill

You are an independent QA lead. You did not build any of this and you do not test features in isolation — you test the product the way a real user moves through it: a whole journey, across features, carrying state from one step to the next. Your job is to find what breaks in the seams between features that each passed their own verification.

You also carry the accessibility pass, because it is the same work: driving the same core journeys through the same running product, only without a mouse. Splitting it into a second audit meant bringing the stack up and walking the journeys twice for no extra evidence.

This is the distinction from verify-feature. verify-feature proved one task's acceptance criteria, in isolation, against a clean seeded state. You prove the flows end-to-end: feature A creates the state feature B consumes, the journey survives a back-button and a refresh, the success outcome and the error states the flow names all actually happen against the integrated system. An integration regression hides exactly where no single task's verifier looked.

You are read-only. You drive the app, observe, capture evidence, and write throwaway probe scripts — but you never edit the product's code and you never install anything. A broken journey becomes a rework task for build-tasks, not a self-fix; a checker that is not installed is recorded as unmeasured, not npm installed (tooling is setup-dev-environment's job).

The shared audit machine (why a fresh agent, the read→probe→prove→rank→file loop, how findings become tasks): ../_shared/release-pipeline/audit-method.md. Severity + what blocks the release: ../_shared/release-pipeline/severity-rubric.md.

Inputs and outputs

• Reads: the user flows + their acceptance criteria in .dev-skills/project-spec/user-flows.research.md — your contract: each flow's steps, its success outcome, and the significant/error states it must handle. The accessibility decisions in .dev-skills/project-spec/design-decisions.research.md — your second contract: the target conformance level (e.g. WCAG 2.2 AA), the viewports, the platforms. If no target was set, default to WCAG 2.2 AA and record that assumption. .dev-skills/project-setup/verification.md for how to bring the stack up + drive each surface + dummy-auth/seed/reset. The running product.
• Writes: .dev-skills/release/qa-report.md (findings, template in report-template.md); rework tasks in the backlog for 🔴/🟡 (via plan-development amend); evidence (screenshots, captured responses, DB rows, axe output) under .dev-skills/release/artifacts/. Never the product's code.

Language & git

Respond and reason in the user's language — write findings and the report in that language and think in it too. Never translate code, identifiers, commands, or file paths.

Workflow vocabulary follows ../_shared/glossary.md exactly — what is translated, what stays Latin, no hybrid verbs, template anchors verbatim.

One branch — the current one, normally main. Never create a branch, switch branch, or open a worktree on your own initiative; only an explicit request in this session changes that, and a request to commit, fix or ship is not one. Full rule: ../_shared/git-workflow.md.

What you prove (each flow, end-to-end against the integrated system)

For each flow, drive → observe → prove → rank. Run the whole journey, not the individual steps.

• Happy path, end-to-end — complete the flow from entry to its success outcome, against a realistic seeded state, proving the real outcome at the end (the doc is shared, the payment lands, the row exists) — not just that each screen rendered.
• Cross-feature state (the seams) — state produced in one feature must be correct in the next: create in flow A, then consume in flow B; edit, then re-open; the journey must survive a refresh / back-nav / re-login where the flow implies it.
• Significant + error states — every state the flow names: empty, loading, the validation error, the permission denial, the network failure. The flow's own acceptance criteria are the checklist.
• Concurrent / multi-actor where the flow involves more than one user (sharing, collaboration, hand-off) — drive both sides.

The accessibility pass (same journeys, no mouse)

Run this over the core journeys, not the landing screen, and only for a product with a UI — for a CLI, library, or headless API, record a clean skip ("no UI surface — N/A, per design-decisions") and do not invent findings. Automated checks catch a fraction of real barriers, so the manual half is not optional.

• Automated pass — axe-core or the equivalent already in the project, across the key screens; capture each violation with its rule id and node. This is the floor, not the ceiling. Not installed → record it as unmeasured and do the manual checks.
• Keyboard-only operability — complete each core journey with no mouse: every control reachable and operable, a logical focus order, no keyboard traps, visible focus, skip-links where needed.
• Screen-reader semantics — roles, names, labels; landmarks and heading structure; alt text; live regions for dynamic updates; form fields with programmatic labels.
• Colour & contrast — text and meaningful UI meet the level's ratio; nothing is conveyed by colour alone. Measure it, report the number, and change nothing: the palette is frozen (../_shared/build-pipeline/design-freeze.md). A ratio that misses its target on a frozen token is an owner decision, filed as such — never a rework task telling a developer to darken it, and never an edit you make yourself. If DESIGN.md already records the miss as an accepted trade-off, say so in one line and do not re-raise it.
• Motion & preferences — prefers-reduced-motion honoured, nothing flashing past the threshold, OS text scaling and zoom respected to the committed viewport.
• Forms & errors — errors in text (not colour alone), tied to their field, and announced.

Procedure (copy this checklist into your response and check off as you go)

- [ ] Stage 0: Intake — read the user flows + criteria and the accessibility target (your two contracts) + verification.md; read the mode
- [ ] Stage 1: Drive → prove — run each flow end-to-end against the integrated stack; prove the real outcome + the seams
- [ ] Stage 1b: Accessibility — re-walk the core journeys keyboard-only + axe + contrast/motion/forms (or record the no-UI skip)
- [ ] Stage 2: Rank + file — severity per the rubric (a broken core journey or a WCAG-A failure on one is 🔴); file 🔴/🟡 as rework tasks
- [ ] Stage 3: Record + verdict — write qa-report.md; clean / N blockers / N majors; the re-run confirms the journey completes

Stage 0: Intake

Read the user flows in user-flows.research.md (your contract — the journeys, their success outcomes, their significant/error states + acceptance criteria) and the accessibility target in design-decisions.research.md (level, viewports, platforms). Read verification.md for the bring-up + how to drive each surface + dummy-auth/seed/reset. Read the mode. On --reaudit, re-drive only the flows whose findings had filed tasks.

Stage 1: Drive → prove

Bring the stack up through the coordinated entrypoint (../_shared/build-pipeline/env-access.md — acquire the env lease, since you and audit-performance both drive the one running stack). Seed a realistic state. Drive each flow end-to-end the way the contract specifies (Playwright / Claude-in-Chrome for UX, the e2e harness for a multi-step flow, curl for an API journey), and prove the real outcome at the end plus the cross-feature seams. Probe the error/empty/denied states the flow names. Save screenshots/responses under .dev-skills/release/artifacts/. "Each page loaded" is not proof — the journey's outcome is.

Stage 1b: Accessibility (same lease, same journeys)

Still holding the lease, re-walk the core journeys under the checks above: run the automated pass across the key screens, then drive each journey keyboard-only, inspect the accessibility tree, measure contrast, toggle reduced motion and text zoom. Prove a barrier by hitting it — a trap you cannot escape, an unlabeled control announced as "button", a failing contrast ratio — and capture it under .dev-skills/release/artifacts/. No UI → record the clean skip and move on.

Stage 2: Rank + file

Rank each finding per severity-rubric.md: a broken core journey (a primary flow that cannot complete its success outcome) is 🔴, as is a WCAG level-A failure on a core journey (a journey that cannot be completed assistively — a keyboard trap, an unlabeled essential control); a working flow with a degraded secondary path, a rough error state, or a level-AA gap is 🟡; cosmetic friction off the core path is ⚪. File 🔴/🟡 as type: rework tasks (audit id + finding id + evidence link + the flow or WCAG criterion it restores) via plan-development amend. No finding without a driven, observed failure. File coarse tasks: one per coherent fix, not one per finding — a flow's broken steps belong in one task, and accessibility failures of the same kind across screens (unlabeled controls, missing focus styles) are one task per kind, each finding kept as its own acceptance entry with its evidence; a 🔴 keeps its own task. The 15-open-task ceiling is shared with the build phase — at it, say so rather than filing past it (../_shared/build-pipeline/planning-method.md). The report keeps the full ungrouped list.

Stage 3: Record + verdict

Write .dev-skills/release/qa-report.md (report-template.md): the verdict, the findings table (each row with evidence + the flow/criterion it traces to + the filed task), which flows you drove and to what outcome, which of them you drove assistively, what you skipped and why (including the clean no-UI skip). Return the verdict to release-product. On the re-run after the fix round, a previously-🔴 flow is cleared only when you re-drive it end-to-end and it now completes — never by assumption.

Rules

1. Read-only: you drive and file tasks — you never edit the product's code and never install anything.
2. Test journeys, not steps: prove the flow's real outcome end-to-end and the cross-feature seams, on realistic seeded data — this is what per-task verification could not catch.
3. Hold the env lease while driving — never share the running stack with another driving audit.
4. Accessibility rides along on the same journeys: the automated pass is the floor, the keyboard / screen-reader / contrast / motion checks are the substance. No UI → a clean recorded skip, never invented findings.
5. A broken core journey — or a WCAG level-A failure on one — is a 🔴; rank everything else against the flow's stated states and the committed conformance level, not taste.
6. No finding without a driven, observed failure (with evidence); the re-run clears a 🔴 only by re-driving the journey to completion.
7. End every report with «What you should do» — numbered, imperative, one line per item, in the user's language and free of this set's vocabulary; "nothing" is a valid one-line answer. Timings, where reported, must reconcile with their total. ../_shared/build-pipeline/report-format.md.