An agent skill that finds what users need but nobody wrote down — by forcing the agent to live through the product as the user, not review it as the builder.
Works as a portable skill for Claude Code, Codex, Gemini CLI, Grok, and any agent you can hand a prompt to.
Ask an AI agent to "review this product for what's missing" and you reliably get:
- findings organized by the system's components, or by Critical/Nice buckets
- generic UX best-practices (add onboarding, add tooltips, add notifications) that fit any product
- one pass, then "here are the top 3 fixes" — done
- a single implied user, happy-path only
- guesses presented as facts
It looks competent and misses the things that actually hurt — because it reviewed the artifact from the builder's chair instead of living the user's intent.
It starts from the user's SEED intent (Jobs-to-be-Done) and walks it first-person (Cognitive Walkthrough): what does this person actually try to do, step by step, and where do they reach for something that isn't there. Then it forces three things out of every walk:
- 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.
Gaps are decomposed by layer — data / backend / wiring / frontend — so "the fix" isn't assumed to be a frontend tweak. A missing "notify me before the deadline" can pull work from data collection up through the UI.
A guide you can skim is a guide you'll skip. This one has gates:
- Output gate — every round must produce the SEED spec, the first-person walk, the three findings, and a layered gap table. Blanks aren't allowed.
- Lens gate — four self-checks void a round if you slipped into system vocabulary, emitted a generic checklist item, skipped empty/failure/return states, or tried to quit on a "good enough" feeling.
- Convergence gate — it loops across different personas until two consecutive new-lens rounds find nothing new (or a user-named count is exhausted). Declaring "done" early, without the evidence block, is a violation. No lazy convergence.
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.
The skill is plain text with no platform-specific tooling, so it ports across agents. It was validated by running the same product under "be quick" time pressure on four different agents:
| Agent | Rounds | Converged | Gate-compliant |
|---|---|---|---|
| Claude | ✅ | ✅ | ✅ |
| Codex | 6 | yes (dry) | ✅ |
| Gemini | 6 | yes (dry) | ✅ |
| Grok | 12 | yes (dry) | ✅ |
All four resisted the pressure to stop after one pass, rotated personas, and printed convergence evidence. A "lazy" agent submitting to the gates is the whole point.
This is an Agent Skill. Drop the folder into your agent's skills directory:
# Claude Code
git clone https://github.com/sergiobuilds/ux-workflow-check ~/.claude/skills/ux-workflow-check
# Codex / Gemini CLI / others: place it in that agent's skills directory,
# or just paste SKILL.md into your prompt — it's self-contained.Then trigger it: "UX check this", "find what's missing for users", "workflow gaps", or name a count: "run it 10 times."
- Plan stage — point it at a spec/plan to catch missing steps and assumptions before building.
- Audit stage — point it at a built product (or live URL/CLI) and have it actually drive the flow to fill in observed (vs inferred) gaps.
It applies to anything a user consumes: web UI, CLIs, reports, docs.
See reference/example-dealradar.md for a full worked walkthrough on a fictional product.
Test-driven, the way skills should be: baseline runs without the skill were observed failing in five specific ways; the gates were written to block exactly those, then re-verified across the four agents above. Roots: Jobs-to-be-Done (start from intent) + Cognitive Walkthrough (walk it first-person), extended with full-stack layer decomposition and a forcing convergence loop.
MIT — see LICENSE.