Qq Audit UX

Part of Claude Code operator skills: a collection of skills for running a real Claude Code setup.

Audit UX with expert personas

Run a full serial UX audit using 20 deep expert persona frameworks, fixing critical issues and verifying each framework before proceeding to the next.

20 usability frameworks, each loaded as a deep expert persona into its own agent context. Serial execution: one framework → fix critical issues → verify → next. Each agent thinks like a 20-year specialist in that specific framework.

Supersedes: ux-framework-audit v2, deep-product-sweep v1, product-qa suite.

Modes

This skill responds to three modes based on the args passed. Interpret intent loosely: fuzzy matching, not exact phrasing.

Mode 1: Full serial audit (no args or "run all")

Triggers: /qq-audit-ux, "run all", "full audit", "everything", no args at all.

Mode 2: Single framework (framework name + optional scope)

Triggers: /qq-audit-ux Fitts's Law, "just run gestalt on the sidebar", "nielsen's on the settings page", etc.

Match the framework name fuzzily: "fitts", "fitt's law", "target sizes" should all match Fitts's Law. "nielsen", "heuristics", "10 heuristics" should all match Nielsen's. If ambiguous, show the 2-3 closest matches and ask.

Mode 3: List frameworks (help/list/discovery)

Triggers: "list", "what do you have", "what frameworks", "help", "which ones", "show me", etc.

Show the framework table from §Framework inventory below, then ask which one(s) to run.

Smart interview (runs before any audit)

DO NOT ask dumb questions. Before asking anything, gather what you already know:

1. Check conversation context: What product are we working on? What files have been discussed? What has the user been complaining about?
2. Check project CLAUDE.md: Product description, tech stack, target audience.
3. Check recent session state: What was just built or changed?

Pre-fill and present assumptions:

"Here's what I know going in:

• Product: [name] ([description from context])
• Platform: [desktop/mobile/both, inferred from tech stack]
• Quality bar: [SUS target, from previous audits or conversation]
• Known pain points: [what the user has mentioned or what recent changes suggest]
• Scope: [full app / specific pages / specific component]

Anything wrong or missing?"

Always ask the target score using AskUserQuestion:

• "What score are you targeting per heuristic?"
  • 9+ (internal tool, chase perfection): fix everything below target
  • 8 (client project, good buy-in): fix criticals, note the rest
  • 7 (client project, conservative): don't risk changing things they like
• The target determines which findings get fixed vs. noted. Only fix findings that bring a heuristic below the target.

Use AskUserQuestion with multiple choice ONLY for genuine gaps. For example, if you truly can't tell whether it's desktop-only or responsive, ask. If you can infer it, state the inference.

Interview output becomes the audit context: passed to every framework agent so they audit with purpose, not generically.

Execution flow (full audit)

Phase 1: Context gathering

1. Run smart interview (above)
2. Read the product's key pages/components to understand scope
3. Take screenshots if browser agent is available

Phase 2: Serial framework execution

For each framework (in order 1-20):

1. Spawn one agent with these instructions:

   • "Read the framework subskill file at ~/.agents/skills/qq-audit-ux/frameworks/[NN-name].md"
   • "You ARE the expert described in that document. Think like them, not like a generalist."
   • "Audit [product name] focusing on [scope]. Context: [interview output]"
   • "Previous frameworks found these issues: [cumulative findings list]. Do NOT re-report duplicates."
   • "Score 1-10, list findings with file:line references, fix critical issues (score < 7), write report."

2. Collect the agent's output:

   • Score for this framework
   • Findings (new, not duplicates)
   • Fixes applied
   • Items flagged for downstream frameworks

3. Verify build if fixes were applied (npx next build or equivalent)

4. Update cumulative state:

   • Add findings to the dedup list
   • Update the running score card
   • Note cross-framework flags for upcoming frameworks

5. Move to next framework

Phase 3: Synthesis

1. Run framework #20 (SUS Scoring) as the final meta-evaluation
2. Compile consolidated report:
   • Overall SUS score
   • Per-framework scores
   • All findings grouped by severity
   • Fixes applied (with file:line)
   • Remaining items for future rounds
3. Compare to previous audit rounds if they exist

Phase 4: Report

Exec summary is MANDATORY: every report starts with a 3-5 sentence executive summary at the very top. No jargon, no framework names. Just: what was audited, what the score is, what the biggest problem is, and whether it improved from last time.

Per-framework exec summaries too: after each framework completes, present a 1-2 sentence summary before the detailed findings. Lead with the score change and the single most important finding.

Save to project's data directory:

• data/audit-ux-[date].md: full report (exec summary at top)
• data/audit-ux-[date]-summary.md: scores + critical findings only

Framework inventory

Key principles

• Serial, not parallel: 70% of findings duplicate across frameworks. Serial means each round finds genuinely new issues after fixes.
• Fix before moving on: don't accumulate a findings list. Fix each framework's criticals before the next audit.
• Expert persona, not checklist: each agent IS the specialist. They reason from principles, not rules.
• Hold every fix to a real quality bar: is this real data? Does it prevent errors? Is the complexity earned?
• Code + screenshots: code audits miss visual issues. Always audit rendered output when possible.
• Multi-round: after all 20 frameworks, run the full cycle again. Scores increase each round until plateau.
• Dedup across frameworks: each agent receives cumulative findings so they don't re-report known issues.

Proven results