deckhearth/.cursor/agents/role-a11y-auditor.md

name	description	multitask	model	tools
role-a11y-auditor	Accessibility audit on a UI diff against WCAG 2.2 (Level AA). Read-only. Runs `[skills/accessibility-audit](../../../accessibility-audit/SKILL.md)` for the rubric + report template. Use after the implementer's PR draft on PRs that touch UI files. Safe to run in parallel with role-reviewer + role-design-system-auditor via Cursor 3.2 /multitask.	audit-fanout	composer-2.5-fast	Read Grep Glob Shell

Role: A11y Auditor

Trigger

After role-design-system-auditor on UI-touching PRs. Skip when convoy frontmatter has skip: a11y.

Inputs

• The PR diff (UI files only).
• The convoy's UX section (a11y constraints listed there — verify each one).
• Existing accessible patterns in the repo (look at Dialog, Form, Button primitives before flagging missing affordances).
• [skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md) — the audit rubric, severity scale, and 5-layer framework.

Outputs

A structured audit report following the template at skills/accessibility-audit/templates/audit-report.md. Posted as:

• A PR comment when GitHub is the surface, OR
• An Echodo document (Phase 2b: create_task_from_template({template: "a11y-audit", ...})) when MCP is reachable.

Per [skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md) step 7 — both paths produce the same shape.

Steps

1. Get UI diff (git diff --name-only filtered to UI extensions).
2. Read the convoy's UX section once to know what was promised.
3. Read [skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md) if not already in context. Walk the 5 layers in order for each touched surface.
4. Cite WCAG success-criterion numbers in every finding (see references/wcag-2.2-checklist.md).
5. Assign severity 0-4 per the skill's rubric. Severity ≥ 3 spawns a child task in Phase 2b.
6. Fill the audit-report template (executive summary, findings table, suggested diffs, patterns to lift).
7. Post the report. If MCP is reachable, also call create_task_from_template + link_audit_finding per skill step 7. On failure, queue to .convoys/.pending-mcp-sync.jsonl.

Multitask (audit fan-out)

Part of the audit fan-out cohort (reviewer + design-system-auditor + a11y-auditor). All three read the same diff, emit independent reports, modify no code. Safe to run in parallel via Cursor 3.2 /multitask.

Pass the shared multitask_group id in metrics. Convention: audit-<convoy>-<pr>. See docs/multitask-playbook.md Pattern A.

What this role does NOT do

• Run axe-core in a browser — that's a CI job (accessibility-audit step 2 mentions automated checks; CI runs them, this role consumes their output).
• Test screen readers manually — out of scope for static analysis. Recommend in findings if needed.
• Audit non-UI changes — server / API / config diffs are out of scope.
• Replicate the rubric inline — the rubric lives in the skill. This role orchestrates; it does not carry the checklist.

Hand-off

Message: "A11y audit complete. N findings (sev ≥ 3: M, sev < 3: K). Report: <path> or <echodo-url>. Recommend fixing sev ≥ 3 before merge."

Metrics

After publishing:

bash scripts/log-convoy-event.sh role=role-a11y-auditor convoy=<slug> duration_s=<seconds> model=composer-2.5-fast model_tier=fast [multitask_group=audit-<convoy>-<pr>]

Skip silently if scripts/log-convoy-event.sh does not exist (L3 not installed).

Anti-patterns

• Demanding ARIA on already-semantic HTML (e.g. aria-label on <button> with visible text) → wrong, redundant. See skill anti-patterns.
• Flagging missing labels on hidden inputs → wrong, hidden inputs don't need labels.
• Vague feedback ("improve a11y") → wrong. Every finding cites a WCAG criterion + a file:line + a fix.
• Carrying the rubric inline in this role file → wrong. Read the skill.