ux-heuristic-review

UX Heuristic Review

Evaluates the implementation against usability heuristics. Runs ALONGSIDE the core quality-review skill at the review phase. When installed, this review is mandatory — it cannot be skipped by the agent.

Mode: BUILD (light) — Critical Four

Evaluate the implementation against the four heuristics most likely to catch user-facing failures. Takes ~2 minutes per task.

H1: Feedback — Visibility of System Status

• Does every button/action produce visible response?
• Are there loading indicators for async operations?
• Does the user know if their action succeeded or failed?
• Is there any action that results in silence? → Silence after user action = FAIL

H3: Control — User Control and Freedom

• Can the user undo or cancel actions?
• Can they dismiss modals and dialogs?
• Does the back button work correctly?
• Are destructive actions protected by confirmation? → No undo on destructive action = FAIL

H5: Prevention — Error Prevention

• Are inputs constrained where possible (dropdowns, datepickers, type validation)?
• Does inline validation catch errors before submission?
• Are dangerous options visually distinct from safe ones? → Free text where a constrained input would prevent errors = FAIL

H9: Recovery — Help Users Recognize and Recover from Errors

• Are error messages in user language (not developer jargon)?
• Does each error message say what went wrong AND what to do next?
• Is form data preserved on validation failure?
• No HTTP status codes, field names, or stack traces in user-facing messages? → Technical error message shown to user = FAIL

Mode: ARCHITECT (full) — All Ten Heuristics

Evaluate against all 10 Nielsen heuristics plus Norman's design principles. Takes ~10 minutes per major feature.

Additional Heuristics (beyond the Critical Four)

H2: Real-World Match — Does the interface use the user's language? Are icons and metaphors recognizable? Is information organized the way users think?

H4: Consistency — Are the same actions called the same thing everywhere? Do similar elements behave the same way? Does it follow platform conventions?

H6: Recognition over Recall — Are all available actions visible? Do forms show expected formats? Can users see previous selections when making new ones?

H7: Flexibility — Are there keyboard shortcuts for frequent actions? Can expert users bypass introductory steps? Does it remember preferences?

H8: Minimalism — Is there unnecessary text? Are visual elements serving a purpose? Is the visual hierarchy clear?

H10: Help — Is contextual help available for complex features? Are tooltips concise and useful?

Norman's Principles Check

In addition to Nielsen's heuristics, check:

• Affordances: Do interactive elements look interactive?
• Signifiers: Is it clear what's clickable, draggable, editable?
• Mapping: Do control positions correspond to what they affect?
• Conceptual Model: Does the interface communicate how the system works?

Severity Classification

Each finding gets a severity:

Severity	Definition	Action
Catastrophic	User loses data or can't complete primary task	MUST fix before merge
Major	User significantly confused or frustrated	SHOULD fix before merge
Minor	User notices oddity but works around it	Fix in next iteration
Cosmetic	Violates principle but minimal user impact	Note for polish

Produce: heuristic-assessment artifact

## UX Heuristic Review: [feature name]
Date: [date]
Mode: [BUILD light / ARCHITECT full]

### Findings

1. [H9 - MAJOR] Error message on login form says "401 Unauthorized"
   → Should say: "Wrong email or password. Check your details and try again."
   → Fix: Update error handler in login-form.tsx

2. [H1 - CATASTROPHIC] No loading state on payment submission
   → User clicks "Pay" and sees no response for 3-5 seconds
   → Fix: Add loading spinner to submit button, disable during processing

### Summary
- Catastrophic: 1 (must fix)
- Major: 1 (should fix)
- GATE RESULT: FAIL (catastrophic finding blocks merge)

References

• heuristic-evaluation.md — Full heuristic descriptions and checkpoints
• usability-principles.md — Krug's laws and Norman's principles
• error-and-recovery-design.md — Error taxonomy for H5/H9 evaluation