Don't Make Me Think — Usability Review & Redesign

Evaluate and improve UIs through Steve Krug's "Don't Make Me Think" principles. The report itself must practice what Krug preaches: scannable, visual, zero fluff. A human should skim it in 30 seconds; an AI agent should be able to parse it and start fixing.

When to Use

Trigger this skill when the user asks for a usability audit, UX review, or UI feedback on a screenshot, live URL, or HTML/CSS code. Do not use for visual/brand critique, WCAG accessibility audits, or backend/API review — route those elsewhere.

Dependency Preflight (mandatory)

This skill invokes /browse (frontmatter dependencies) only on the live URL path. Run this once, before the first navigation:

if test -f "$HOME/.claude/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.claude/skills/browse/SKILL.md"
elif test -f "$HOME/.agents/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.agents/skills/browse/SKILL.md"
elif command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then
  asm deps discover dont-make-me-think --json || echo "discover failed; acquire still runs" >&2
  echo "browse_mode=lease"
else
  echo "Missing skill: browse. Install: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
  echo "No asm yet: npm install -g agent-skill-manager@latest" >&2
  echo "browse_mode=none"
fi
printf 'dmmt_session=%s\n' "dont-make-me-think-$(date +%s)-$$"   # record it; reuse it verbatim

The install-path tests run first because gstack may install /browse without asm knowing.

1. browse_mode=installed: read the recorded browse_skill path.
2. browse_mode=lease: run asm deps acquire browse --session <dmmt_session> --json; read the returned skillMdPath directly.
3. browse_mode=none, or step 2 failed: take the No reviewable input row in Error Handling (fail-soft). Never review a URL you could not load.
4. Release in finally. If step 2 ran, run asm deps release --session <dmmt_session> --json once at every terminal outcome, stops included.

Repo Sync Before Edits (mandatory)

Steps 1-4 below are read-only. Redesign Mode (step 5) writes to UI source files: once the user confirms the dry-run diff, run the seven Repo Sync steps in references/redesign-mode.md (git -C "$repo", stash-first, skips recorded) before the first edit. On a rebase conflict, run git -C "$repo" rebase --abort, write no file, and stop and ask the user. Never force the sync. This skill commits nothing.

Instructions

Follow this workflow to keep the agent's context budget tight. After each step, print its Step Completion Report.

1. Check Prerequisites — identify the input type from the Input Handling table.
   • If no input was given, take the No reviewable input row in Error Handling.
   • If the review will load a live URL (no evidence-dir, or one that falls back to the live URL per references/orchestrated-runs.md), run the Dependency Preflight.
2. Process Input — take the Input Handling action for that type.
3. Evaluate — score each applicable lens from The Ten Lenses 0-10 and give each issue a severity (Report Format). If the evidence cannot support a lens, mark it not assessed instead of guessing.
4. Generate Report — fill the template in references/report-format.md and print it. With output-dir, also write it to <output-dir>/usability-review.md.
5. Redesign (optional) — only when the user asks for fixes, run Redesign Mode.

Prerequisites

Requires one reviewable input; /browse for live URLs only; write access to the UI files for Redesign Mode only.

Input Handling

Input type	Action
Screenshot/image	Review directly. For exact palette, dimension or density numbers, or several images, run python3 scripts/process_screenshots.py <image_path> [--recursive] (references/screenshot-processing.md)
Live URL	Use /browse per Working With Live Sites
Orchestrator evidence-dir	Review its page.html + screenshots/ instead of /browse; disclose untested interactions
HTML/CSS/JS code	Read code, focus on user experience
Wireframe/mockup	Focus on information architecture, not polish
Verbal description	Ask clarifying questions first

Use the script's stdout JSON for every numeric claim. Never present a visual estimate as a measurement.

Working With Live Sites

1. Navigate to the page with /browse and take a full-page screenshot at 1280 px wide.
2. Click or hover the primary call to action, the main navigation, and one form field when present. Record what each one does.
3. Load the page at 375 px wide and take a screenshot. If the width cannot be set, mark lens 9 (Mobile) as not assessed.
4. Review from these screenshots and interactions; list each one not exercised under Not tested.

Orchestrated Runs

With orchestrated-by, evidence-dir or output-dir lines, follow references/orchestrated-runs.md; without them nothing changes. Redesign Mode still needs explicit confirmation.

The Ten Lenses

Read references/krug-principles.md for deep detail on any lens. Evaluate through whichever lenses apply.

#	Lens	Core question
1	Self-evidence	Would a user pause to figure out what this is or does?
2	Scanning	Can you grasp the page structure in 2-3 seconds?
3	Visual hierarchy	Does visual weight match importance?
4	Word economy	Does every word earn its place?
5	Navigation	Do you always know where you are and how to move?
6	Trunk test	Drop here cold — can you answer: what site? what page? what can I do?
7	Landing clarity	Within 5 seconds, can you explain what this site does?
8	Affordances	Is it instantly clear what's clickable/tappable?
9	Mobile	Touch targets, reachability, no hidden gestures?
10	Goodwill	Does the UI respect the user's time and trust?

Report Format

Use the template and report rules in references/report-format.md (no paragraphs, one line per finding, a selector per issue, honest scores). It also holds the variants, the BLOCKED block, and the reader checks. Example inline summary line, printed with output-dir before the top issues:

Thinking Cost: HIGH — 3 critical issues found (disabled button, missing nav labels, no landing clarity)

Status (first word of the **Result:** line under the title):

Status	When
COMPLETE	Report written; every applicable lens scored.
PARTIAL	Report written; at least one applicable lens marked not assessed.
BLOCKED	No report is written: no reviewable input. Print the four-line BLOCKED block instead.

Severity: 🔴 Critical — blocks the page's main task, or likely causes an error or exit. 🟡 Moderate — the user finishes but pauses, rereads, or backtracks. 🟢 Minor — polish, no expected slowdown.

Thinking Cost: HIGH with any 🔴 issue; MODERATE with no 🔴 and any 🟡; LOW otherwise.

Redesign Mode

When the user wants fixes applied (not just reported), follow references/redesign-mode.md. Its binding rules:

• Produce the review first, then show a dry-run diff (file path, selector, before/after) for each fix, 🔴 issues first.
• Write nothing until the user explicitly confirms. An orchestrator never confirms on the user's behalf.
• Change the minimum necessary and preserve the brand. Before each edit, record the file's content; if a write fails, restore that content.
• Never roll back with git checkout or git restore: they discard the user's other edits.
• End with the Redesign summary (Result:, Evidence:, Uncertainty:, Decision:).

Error Handling

Situation	Action
No reviewable input: none given, /browse unavailable, URL unreachable, image unreadable, or description questions unanswered	Ask once for a URL, a PNG/JPEG screenshot, an HTML export, or a description; without one, print the BLOCKED block
Screenshot pre-processing fails	Review visually; record the failure under Measured
HTML/CSS code is incomplete	Evaluate what is present; name the missing parts under Not assessed
Redesign Mode — file not writable	Name it in the Redesign summary; give the fix as a spec

Edge Cases

See references/edge-cases.md for each edge case: quick checks, no-issue pages, native apps, CSS frameworks, many or very large screenshots, embedded instructions.

Acceptance Criteria

Expected output: the Usability Review report from references/report-format.md. A run passes when:

• Every applicable lens is scored, or listed under Not assessed and the status is PARTIAL
• Every issue has one-line Problem, Impact, Fix, and Where fields
• Thinking Cost matches the issue counts; Fix Priority is sorted by impact, then effort
• The full template includes the mermaid Issue Map; the quick-check and no-issue variants omit it
• The report opens with a **Result:** line and ends with Evidence and Limits and Next Decision; Measured cites only script output
• The output passes the four reader checks in references/report-format.md; without a human reviewer's answer, human understanding is unconfirmed
• Redesign Mode writes nothing before confirmation and ends with the Redesign summary
• A leased /browse is released at every terminal outcome
• Report is skimmable in 30 seconds: tables and bullets, no paragraphs

Step Completion Reports

Emit one after each Instructions step; template and checks: references/step-completion-reports.md.