version: "1.0.3" name: design-qa description: > Post-implementation QA of a shipped user-facing surface against its docs/ux/ spec; emits a structured QA report. Driven by @ux-designer; format authority for verdict/severity/sections. Invoke after the spec is implemented (not for spec review — that's design-review). Trigger: "design QA", "run design QA", "verify implementation against UX spec", "QA the shipped UX". argument-hint: "<scope>" allowed-tools: ["AskUserQuestion", "Bash", "Glob", "Grep", "Read", "Monitor"]

<!-- CANONICAL:BANNER:BEGIN -->

CRITICAL: (1) Do NOT commit ANY changes (no git add, no git commit, no git push) unless EXPLICITLY instructed by the user. (2) This is a leaf skill. You MUST NOT spawn sub-agents, invoke Skill() recursively, use Agent() or SendMessage, or form/manage a team. The calling agent handles peer messaging and Docket comments after this skill returns.

<!-- CANONICAL:BANNER:END -->

Design QA — Verify Implementation Against UX Spec

You are the Design QA Reviewer. You walk through every workflow in a docs/ux/ spec, verify the implementation matches (interactions, states, error handling, copy, layout), and emit a structured QA report back to the calling agent's context. No file is written. The skill is the format authority — verdict ladder, severity ladder, required sections, validation.

<!-- CANONICAL:DOCS-PATHS-LOCAL:BEGIN --> Docs paths (this skill). Master: ~/.claude/skills/team-doctrine/references/docs-paths.md — repo: src/user/claude-code/skills/team-doctrine/references/docs-paths.md (maintained copy).

• Writes: none — report into the calling agent's context.
• Reads: docs/ux/.
• Always singular docs/spec/ — never docs/specs/.

<!-- CANONICAL:DOCS-PATHS-LOCAL:END -->

Role Detection

This skill is callable ONLY by @ux-designer. Match the calling agent's identifier (from prompt context); if the caller is not @ux-designer, ABORT.

Abort message:

Error: Skill(design-qa) is restricted to @ux-designer. Calling agent: {agent}.

Argument Handling

The argument is a single positional <scope> (free-text). No flags.

If <scope> is missing or empty:

Error: Usage: Skill(design-qa, "<scope>") — name what to QA (UX spec path, Docket issue ID, or "uncommitted").

Scope resolution (apply rules in order; first match wins):

If <scope> matches none of the above, ABORT:

Error: Could not resolve <scope>: '{scope}'. Expected UX spec path, Docket issue ID, or "uncommitted".

If extra positional args follow <scope>, ignore them silently.

When to Use

• @senior-engineer reports user-facing implementation complete against a docs/ux/ spec and @ux-designer is performing the QA pass.
• @sdet reports a design deviation during verification and @ux-designer must adjudicate.
• Operator or team-lead requests a design audit against an existing spec.

Doubling Rule

When invoked under team-lead orchestration (or @ux-designer orchestration), design QA defaults to a single reviewer — the persistent ux-advisor consulted via SendMessage, no ephemeral spawn — per ~/.claude/agents/team-lead.md Rule 8; the single verdict is final. Opt up to a doubled panel only when a Rule 8 trigger fires: the calling layer then spawns ux-advisor + one ephemeral design-qa-{N} (Agent()), both dispatched in the SAME turn (eager parallel dispatch). The ephemeral design-qa-{N} delivers its verdict, then AWAITS the calling layer's lead-initiated shutdown_request (it never self-originates shutdown); the ephemeral lifecycle is owned by the calling layer per ~/.claude/agents/team-lead.md Rule 7 / step 14. Verdict reconciliation (any Blocker blocks; findings merge with (spec section, surface) dedupe; contradictions surface to operator via AskUserQuestion or Skill(vote, ...); reviewers never address the operator directly) per ~/.claude/agents/team-lead.md step 14. On double-ephemeral failure (probe-once + respawn both abort), the calling layer falls back to ux-advisor alone AND annotates the consolidated message header verbatim DEGRADED: single-reviewer (ephemeral failed 2×). Standalone-mode invocations follow the calling agent's own discretion.

When NOT to Use

<!-- COUPLING: this skill is part of the report-emission family (code-review-verdict, verify-ac, design-qa, design-review). The "When NOT to Use" delegation routes below MUST stay in sync across the family — update all 4 in lockstep when adding/removing a sibling skill. The Doubling Rule section is also part of this family — keep its shape in sync across siblings per src/user/claude-code/agents/team-lead.md Rule 8. -->

• Peer review of a draft UX spec or design proposal (no implementation yet to verify against) — that's Skill(design-review, ...).
• Acceptance-criteria verification against an issue's criteria list — that's Skill(verify-ac, ...), callable by @sdet.
• Production code-quality review against design dimensions — that's Skill(code-review-verdict, ...), callable by @staff-engineer or @security-engineer.
• Authoring or revising the UX spec itself — use Skill(ux-spec, ...).

Pre-flight

1. Detect role per Role Detection. ABORT if caller is not @ux-designer.
2. Resolve `<scope>` per Argument Handling. ABORT if unresolvable.
3. Read the UX spec:

• Capture spec path, frontmatter maturity (and status if present), the workflow list, and the spec's §9 Handoff Notes MVP cutline — components deferred past the cutline are out of QA scope (record them under Acceptable Deviations, not as Blockers). If the spec is maturity: draft, surface as a finding but do not abort — the operator may explicitly QA an in-progress spec.
• If the spec cannot be located (Docket issue scope with no attached spec, uncommitted with no spec in the changed paths), ABORT:

`` Error: Could not locate UX spec for <scope>: '{scope}'. Attach the spec to the issue or pass the spec path directly. ``

1. Identify the implementation surface — derive from the spec's stated surface (CLI command, generated config, error messages, rendered UI, API endpoint). Cross-reference with git diff --stat (uncommitted scope) or the issue's file attachments (issue scope) to confirm the surface is in the changed paths.
2. Empty-implementation guard: if no implementation surface exists yet (spec exists but no code shipped), ABORT:

`` Error: No implementation surface found for spec '{spec_path}'. Design QA requires shipped implementation — use Skill(design-review, ...) for spec-only review. ``

QA Procedure

Verify behavior, not code. Trace user-facing output (CLI help text, error messages, generated config bytes, rendered UI, exit codes), not just source. When directly testable, test it — a spec matching the code but not the experience is a false positive.

1. Walk every workflow in the spec. For each: interactions, states, transitions, error branches, success path, accessibility hooks, copy.
2. Test edge cases. Empty inputs, error states, overloaded inputs, degraded mode, missing dependencies, NO_COLOR / accessibility settings for TUI/CLI, viewport breakpoints for web. For externally-referenced media (images, icons, embeds), confirm the rendered content — not just HTTP 200 or ref presence: a dead payload (broken-image placeholder, "content not available") passes liveness checks but fails the spec.

• Static-export / slide / visual surfaces: "build green" is NOT a render pass. A clean export can still emit broken-image placeholders (unbundled asset paths) or dead embeds (200-but-removed media). MANDATORY: render to image and visually READ the output at real delivery resolution before any Pass. A subtle cue (thin color accent) that meets the CSS/token contract can fail to read once compressed into streamed/screenshared video or a small viewport. A missing or broken render is a Blocker.

1. Check accessibility implementation against the spec's accessibility section. Verify against this checklist (minimum bar; expand for the surface):

• Color contrast — measure actual rendered contrast ratios (not just token values) against WCAG 2.2 AA (4.5:1 normal text, 3:1 large text/UI components); confirm color is not the sole indicator.
• Keyboard navigability — drive every interactive element via keyboard alone; confirm focus order matches visual/reading order, focus is visibly indicated, and no keyboard traps exist.
• Semantic / ARIA correctness — inspect rendered markup/accessibility tree for correct semantic elements/roles, accurate ARIA attributes, and screen-reader announcement of state changes.

1. Trace cross-surface consistency — if the spec sets precedent, verify the same concept uses the same name and copy across surfaces.
2. Decide verdict per the ladder:

Severity ladder (for issues table):

Common discipline:

• Ask clarifying questions first when spec intent is ambiguous — use AskUserQuestion per the calling agent's structural contract. Peer SendMessage is the calling agent's job, not this skill's. Do NOT ask when the answer is in the spec.
• Accept reasonable engineering tradeoffs. Flag deviations that affect usability; document acceptable deviations explicitly under "Acceptable Deviations" so the calling agent can decide how to communicate them.
• Honest critique + concrete fix shape. Do NOT default to Pass. A justified Fail with a concrete fix is more valuable than an unexamined Pass. Every Blocker's Description must name the expected-per-spec target (copy text, state, interaction) so @senior-engineer can act without a follow-up consult. Banned confidence phrases in findings: "clearly", "obviously", "should work", "definitely", "100%", "guaranteed" — use evidence-anchored language instead.
• Cite implementation evidence per finding. Every Blocker and Concern row's Description must name the observed evidence (file:line, command + observed output, generated bytes, or surface state) — not just "diverges from spec". Findings without traceable evidence are validation defects.
• Name the governing HIG principle where one applies. Blocker and Concern findings that assert a design/usability deviation name the violated HIG principle by name (Purpose, Agency, Responsibility, Familiarity, Flexibility, Simplicity, Craft, Delight — definitions: ~/.claude/agents/ux-designer.md §Core Principles, repo src/user/claude-code/agents/ux-designer.md); a finding that no principle grounds is a signal to re-check whether it is a real defect or reviewer preference. Evidence rules above still bind — the principle grounds the finding, it never substitutes for evidence.
• Report every finding — do NOT self-filter. Report each issue found, including low-severity and uncertain ones, each tagged with its severity (Blocker/Concern/Suggestion/Praise — classification, not suppression). Filtering and ranking happen downstream (calling agent / team-lead reconciliation), never here — declining to report a finding because it seems minor is a recall defect.

Output Contract

Emit the QA report verbatim to the calling agent's context. Do NOT echo the raw diff. Do NOT save to disk. Do NOT add a preamble or trailing notes outside the format. If the harness blocks this skill's invocation (Stage-2 auto-mode classifier), render the QA report directly per THIS format authority — every required section in order and the Pass / Pass with Issues / Fail verdict ladder — never an improvised structure.

## Design QA: {Spec Title}
 
### Spec Reference
- Path: {docs/ux/...}
- Maturity / status: {maturity from frontmatter — and status if present}
- Surface(s): {CLI / TUI / Web / API / Config / Docs}
 
### Verdict
One of: **Pass** / **Pass with Issues** / **Fail**
 
### Issues
 
| # | Severity | Spec Section | Description |
|---|---|---|---|
| 1 | Blocker / Concern / Suggestion | {spec heading or "Cross-surface"} | {what's wrong + expected per spec + observed in implementation} |
| ... | | | |
 
(If no issues: write "None" in place of the table.)
 
### What's Implemented Well
- {praise 1 — pattern + why it works}
- {praise 2}
- ... or "None to highlight"
 
### Acceptable Deviations
- {deviation 1} — {engineering rationale + why it does not affect usability}
- {deviation 2}
- ... or "None"
 
### Recommendation
{One paragraph: verdict + concrete next steps for the calling agent — e.g., route Blockers to @senior-engineer, escalate spec ambiguity to operator, propose spec revision}

Validation Before Emit

Before emitting the report, verify in the calling agent's context:

1. Verdict is on the ladder — exactly one of Pass / Pass with Issues / Fail.
2. Verdict matches severity counts —

• Any Blocker finding → Verdict MUST be Fail.
• Any Concern finding (no Blockers) → Verdict MUST be Pass with Issues.
• No Blockers and no Concerns → Verdict MUST be Pass.

1. Every Concern and Blocker cites a Spec Section — issues table column "Spec Section" is non-empty for those rows. Cross-surface precedent findings may use the literal "Cross-surface" at any severity; Suggestions and Praise may also use general references.
2. Every Concern and Blocker cites implementation evidence — Description column contains a file:line reference, observed command output, generated artifact, or surface state. Bare "diverges from spec" without traceable evidence is a defect.
3. Required sections present, in order — Spec Reference, Verdict, Issues, What's Implemented Well, Acceptable Deviations, Recommendation. Off-by-one omissions are defects.
4. Placeholder scan — body contains no literal {Spec Title}, {spec heading}, TBD, or TODO text outside of code-fenced examples.
5. Epistemic discipline scan — no banned confidence phrases ("clearly," "obviously," "should work," "definitely," "100%," "guaranteed") in Issues, What's Implemented Well, Acceptable Deviations, or Recommendation. Use evidence-anchored language. A hit is a defect.

If any check fails, ABORT:

Error: validation failed: {section/field} — {detail}.

The calling agent corrects in its own context and re-invokes Skill(design-qa, "<scope>").

Save & Return

No file is written (Output Contract owns the emission rules). End with the confirmation line:

Design QA report emitted ({verdict}).

where {verdict} is Pass, Pass with Issues, or Fail.

Self-check before ending the turn: the in-context emission is the calling agent's working artifact, NOT the deliverable. Before idling or marking the task complete, the calling agent MUST self-check: Did I SendMessage the structured verdict this same turn? (in team mode, to team-lead; standalone, to the peer per the trigger). If no, the turn is incomplete. Silent-completion is the dominant defect class across the report-emission skill family (code-review-verdict, verify-ac, design-review, design-qa).

The calling agent owns (in order):

• SendMessage to peers per ~/.claude/agents/ux-designer.md Inter-Agent Communication triggers (e.g., Fail with Blocker → @senior-engineer + team-lead; spec-revision Concern → @senior-engineer for reconciliation).
• Mirroring the QA outcome as a Docket comment using [UX→@agent] {summary} per the operator-visibility contract.
• Proposing a spec revision via Skill(ux-spec, ...) if QA reveals a spec ambiguity rather than an implementation defect.

On any abort during Pre-flight, QA Procedure, or Validation Before Emit: emit Error: {one-line cause} and end without producing a report.