heuristic-evaluation

Heuristic Evaluation

Heuristic evaluation is the usability lens on a build. Where designpowers-critique asks "does this match the plan?" and the accessibility review asks "can everyone access this?", heuristic evaluation asks "will people actually be able to use this without getting lost, confused, or stuck?" This skill dispatches the heuristic-evaluator agent and integrates its findings with the other reviewers.

When to Use

• After design-builder completes a build — run alongside designpowers-critique and the accessibility review, not after them
• Before a fix round, so usability findings are reconciled with craft and accessibility findings together
• When a flow feels confusing but you can't articulate why — the heuristics name the problem
• When evaluating an existing design (see using-designpowers → Review Mode), not just freshly built work

This skill is not optional after a build. Skipping it is a Red Flag (see using-designpowers). Usability problems that craft critique and accessibility audits both miss are exactly what this catches.

Process

Step 1: Confirm Inputs Exist

Before dispatching, assemble:

• The build to evaluate (running app, prototype, or screenshots — test what was built, not the spec)
• The design brief (from design-discovery) — for the key tasks to walk through
• The personas (from inclusive-personas) — each persona's primary task gets a cognitive walkthrough
• design-state.md — the shared state the agent will read and update

If there is no brief or no list of key tasks, the cognitive walkthrough has nothing to walk through. Go back and capture the key tasks first.

Step 2: Dispatch the heuristic-evaluator Agent

Dispatch the heuristic-evaluator agent (see agents/heuristic-evaluator.md). It will:

1. Evaluate the interface against Nielsen's 10 heuristics, citing specific violations with evidence (H1–H10)
2. Run a cognitive walkthrough of every key task — four questions per step
3. Analyse error paths, not just happy paths — recovery, undo, back navigation, dead ends
4. Assess learnability (first-time user) and efficiency (repeat user)
5. Acknowledge what works well, not only what fails

The agent narrates at three moments (arrival, working, departure) per the Agent Transparency protocol in using-designpowers.

Step 3: Run in Parallel and Reconcile

Per the Reconciliation Protocol in using-designpowers, the heuristic-evaluator runs simultaneously with design-critic and the accessibility-reviewer:

design-builder finishes
        |
   ┌────┼────────┐
   v    v        v
critic  reviewer  heuristic    (run simultaneously)
   |    |        |
   └────┼────────┘
        v
  reconciliation

When findings overlap or conflict, classify them (Aligned / Complementary / Conflicting) and resolve using the protocol's priority rules. Remember: usability wins over style — a beautiful interface that confuses people has failed.

Step 4: Honour the Auto-Mode Safeguard

Even in auto mode, the pipeline must pause if the heuristic-evaluator finds a critical H3 violation (no undo on a destructive action) or H1 violation (user is completely lost). These indicate structural problems, not polish issues, and the user should decide how to resolve them.

⚠️ Auto paused: heuristic-evaluator found a critical usability issue (H3 — no undo on delete) that needs your decision. [details]

Step 5: Feed the Fix Round

After reconciliation:

1. The agent's findings join the single prioritised fix list (critical first)
2. Note which findings the heuristic-evaluator sourced and whether any were reconciled with other reviewers
3. Record deferred Minor findings in the Design Debt Register via design-debt-tracker — promises don't disappear because severity is low
4. Re-run the heuristic-evaluator only on critical fixes after the build round, not the full evaluation

What You Get

A structured heuristic evaluation report (see the agent definition for the full format): a heuristic findings table (H1–H10 with verdicts), cognitive walkthrough results per task, findings grouped by severity, what works well, and a recommendation (Proceed / Revise / Rethink).

Integration

• Runs after: design-builder (build complete) — or against an existing design in Review Mode
• Runs alongside: designpowers-critique, accessibility review (parallel, then reconciled)
• Feeds: the reconciliation protocol → design-builder fix round → synthetic-user-testing
• Calls: design-debt-tracker for deferred Minor findings
• Records to: design-state.md (Decisions Log, Handoff Chain, Open Questions)