design-qa

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".

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, dispatch via the task tool, or form/manage a team. The calling agent owns downstream routing and Docket comments after this skill returns. (3) Under Opencode the calling agent is a one-shot task-tool dispatch: this skill emits the structured QA report into the calling agent's context, and the calling agent MUST carry that report body in its returned summary to team-lead (team-lead relays findings to peers). There is no peer-messaging channel and no SendMessage — see Save & Return for the silent-completion self-check.

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.

Docs paths (this skill). Master: ~/.config/opencode/skills/team-doctrine/references/docs-paths.md — repo: src/user/opencode/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/.

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):

Form	Detection	Sources
UX spec path	Bash test -e {path} and path matches docs/ux/.*\.md	Read the spec; locate the implementation surface from the spec's frontmatter and body
Docket issue ID	docket issue show {scope} --json exits 0	Read issue + comments + file attachments; locate the linked UX spec via attachments or docket issue comment list
Literal uncommitted	exact match	git diff + git diff --staged + git diff --stat HEAD; calling agent identifies the relevant spec from changed paths

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, design QA defaults to a single reviewer — the ux-advisor role (@ux-designer), dispatched (or resumed via task_id), no second dispatch — per ~/.config/opencode/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 issues two task calls in ONE message (concurrent dispatch) — ux-advisor (resumed via task_id) + a fresh one-shot design-qa-{N} (@ux-designer); each reviewer is a one-shot task dispatch that returns its verdict in its summary, then ends. Dispatch mechanics and lifecycle are owned by the calling layer per ~/.config/opencode/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 question or Skill(vote, ...); reviewers never address the operator directly) per ~/.config/opencode/agents/team-lead.md step 14. On double-reviewer failure (re-dispatch twice both abort), the calling layer falls back to ux-advisor alone AND annotates the consolidated message header verbatim DEGRADED: single-reviewer (one-shot reviewer failed 2×). Standalone-mode invocations follow the calling agent's own discretion.

When NOT to Use

• 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 Handoff Notes MVP cutline (typically a §9 Handoff Notes section — if the spec lacks one, treat the full workflow list as in-scope and note the structural absence under Acceptable Deviations). 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.
     

4. 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.

5. 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). When a render/export command exists for the surface, MANDATORY: render to image and visually READ the output at real delivery resolution before any Pass (the opencode Read tool ingests PNG/PDF attachments). 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. Render-absent fallback: if the project ships NO render/export command for the surface (and none can be invoked via Bash), do NOT fabricate a Pass — emit a Question finding ("render path unavailable — visual QA could not be performed; operator must capture and visually verify at delivery resolution before this surface binds"), do not issue a Pass on that surface, and surface the missing render path to the operator via the calling agent's returned summary so a render step can be added.
3. Check accessibility implementation against the spec's accessibility section (WCAG criteria, keyboard reachability, color-not-sole-indicator, etc.).
4. Trace cross-surface consistency — if the spec sets precedent, verify the same concept uses the same name and copy across surfaces.
5. Decide verdict per the ladder:

Verdict	Meaning
Pass	Every workflow matches the spec; no Blocker or Concern findings; minor Suggestions and Praise allowed
Pass with Issues	Workflows match in core paths; one or more Concern findings present, no Blockers; calling agent annotates the caveats
Fail	One or more Blocker findings: broken workflow, missing critical error state, accessibility regression, or copy/precedent divergence on a shipped surface

Severity ladder (for issues table):

Severity	Meaning
Blocker	Must fix before sign-off: broken workflow, missing critical error state, accessibility regression, cross-surface precedent violation, missing/broken render on a static-export or visual surface (build-green is not a render pass)
Concern	Should fix or explicitly justify: spec deviation that affects usability, missing edge case, inconsistent copy
Suggestion	Consider for this or future iteration: polish, minor improvement
Praise	Pattern worth highlighting and replicating — routes to What's Implemented Well, not Issues

Common discipline:

• Ask clarifying questions first when spec intent is ambiguous — use question per the calling agent's structural contract. Peer relay is the calling agent's job (it surfaces findings in its returned summary for team-lead to relay), 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.
• 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.
3. 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.
4. 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.
5. Required sections present, in order — Spec Reference, Verdict, Issues, What's Implemented Well, Acceptable Deviations, Recommendation. Off-by-one omissions are defects.
6. Placeholder scan — body contains no literal {Spec Title}, {spec heading}, TBD, or TODO text outside of code-fenced examples.
7. 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 ending the turn, the calling agent MUST self-check: Did I include the structured verdict in my returned summary this same turn? (in team mode, to team-lead; standalone, surfaced for team-lead to relay 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):

• Surfacing findings in its returned summary to team-lead per the ~/.config/opencode/agents/ux-designer.md Inter-Agent Communication triggers (e.g., Fail with Blocker → team-lead relays to @senior-engineer; spec-revision Concern → team-lead relays to @senior-engineer for reconciliation); there is no peer-messaging channel.
• 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.