Dont Make Me Think

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

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.