Make AI agents find UX gaps from user intent, not by reviewing the code

#ai #llm #ux #opensource

The failure mode

Ask an AI agent "review this product for what users are missing" and you get a predictable shape: findings grouped by the app's components, a list of generic best-practices (onboarding, tooltips, empty states), and "the top 3 fixes." One pass, done. It looks thorough and misses what actually hurts, because it reviewed the artifact from the builder's chair instead of living the user's intent.

The fix: start from intent, walk it first-person

ux-workflow-check is a portable agent skill built on two old, proven ideas — Jobs-to-be-Done (start from what the user is trying to get done) and Cognitive Walkthrough (walk the task first-person, step by step) — plus full-stack layer decomposition and a forcing loop.

Every round it must produce:

The intent gap — "the builder sees it shaped like X; the user lives it shaped like Y."
Tacit assumptions — what the builder took for granted, and what breaks when each is violated.
Missing screens/features — pinned to specific steps in the walk, not floating wishes.

And gaps decompose by layer — data / backend / wiring / frontend — so the fix isn't assumed to be a frontend tweak.

Why "forcing"

A guide you can skim is a guide you'll skip. This one has gates:

an output gate (no blanks),
a lens gate (four self-checks that void a round if you slipped into system vocabulary or skipped failure/empty/return states),
a convergence gate (it loops across different personas until two consecutive new-lens rounds find nothing new).

The net effect: the agent can't wrap up with "the top 3," can't review one persona and feel finished, and can't pass guesses off as observations.

Built test-driven, verified cross-agent

I ran baselines without the skill and watched them fail in five specific ways, then wrote the gates to block exactly those. I verified it cross-agent: the same product under "be quick" pressure on Claude, Codex, Gemini, and Grok all looped to convergence with full gate compliance. It's plain text with no platform tooling, so it ports anywhere.

MIT. Repo: https://github.com/sergiobuilds/ux-workflow-check