Improve User Experience

Improve User Experience

Surface experiential friction and propose bridging opportunities — changes that close a gulf the user currently has to cross on their own. The aim is a product where a first-time user can form the right intention and confirm the result without help.

Required tooling

Design is how this skill models experience, and it holds that design to a quality bar — so two dependencies are required, not optional:

• Pencil MCP — the .pen design editor. Every read of the designed experience and every bridge you produce goes through it.
• impeccable skill — the visual-craft bar every bridge design is held to. Layered on top of the design, never a substitute for closing the gulf.

Preflight before any design work. If the Pencil MCP tools aren't connected or the impeccable skill isn't installed, stop and ask the user to install/connect them (install commands in skill.deps.json) before continuing — do not fall back to hand-drawn mockups or unpolished designs. (A missing .pen file in the project is fine — that's a project state, not a missing dependency; you'll create one in phase 3.)

Glossary

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "confusing," "clunky," "intuitive," or "clean." Full definitions in LANGUAGE.md.

• Job — what the user is trying to accomplish, in their terms and outcome ("get a refund for a late order"), not the feature or screen.
• Gulf of Execution — the distance between the user's intention and the actions the interface offers. Felt as "how do I do this?"
• Gulf of Evaluation — the distance between the system's actual state and the user's ability to perceive and interpret it. Felt as "did that work? what now?"
• Signifier — a perceptible cue announcing that an action is possible, and where. Distinct from the affordance it advertises.
• Affordance — an action the interface actually permits.
• Feedback — the system's perceptible response confirming what an action did and what state resulted.
• Conceptual model — the model of how the system works that the design projects, and the one the user forms. Good UX makes them match.
• Friction — effort, decisions, waiting, or steps the user spends that don't advance the Job. The quantity being reduced.
• Bridge — a design change that closes a gulf so the user no longer crosses it themselves. The verb of this skill.

This skill is informed by the project's intended experience. EXPERIENCE.md is the human-owned glossary of the experience — Jobs, flows, and feels — that mirrors CONTEXT.md (which names the domain). It is the bar: the skill finds where the built experience falls short of the intended one, and never edits EXPERIENCE.md without explicit human approval — it is the source of truth code conforms to, not the reverse. What graduates into EXPERIENCE.md, into CONTEXT.md, or into a design decision record (DECISION-RECORD.md) — and in what format — is spelled out in phase 3's side effects.

Process

1. Explore

Read EXPERIENCE.md in full and the relevant CONTEXT.md domain terms first. They are the intended experience and the names for it — the bar you're measuring against.

The design is the second source of the bar. EXPERIENCE.md states the intended experience; the .pen design shows it. Open it with Pencil — call get_editor_state({ include_schema: true }) first (.pen files are encrypted: Pencil tools only, never Read or Grep), then read the designed flow with batch_get and capture frames with get_screenshot / export_nodes so the report can show the real designed experience, not a hand-drawn approximation. This unlocks a gulf source the prose misses: drift between the designed experience and the built one — where implementation quietly diverged from the design is often where the richest gulfs hide. If the project has no .pen design yet, there's nothing to compare against — work from EXPERIENCE.md plus the built app, and you'll create the design in phase 3.

Then walk the actual user flows in the area you're touching. Prefer driving the running app so you feel the friction yourself — start it however this project runs and move through the flow as a first-time user (browser automation, where available, lets a sub-agent walk it for you). When the app isn't runnable, trace the flow through the code with the Agent tool. Don't follow rigid heuristics — move through the product organically and note where you experience friction:

• Where does the user have to guess how to start a Job — no signifier for the affordance that does it? (execution gulf)
• Where does the user act and get no feedback — can't tell if it worked or what state they're now in? (evaluation gulf)
• Where does the product's conceptual model contradict what the user already believes, forcing them to relearn it?
• Where does a Job take more friction — steps, decisions, waiting — than the value it returns?
• Where does an error leave the user stranded with no next action?
• Where does the layout itself tax the Job — a frequent action rendered small or far from the user's attention (Fitts' Law), or one needed choice buried among many (Hick's Law)? (friction)
• Where does the built screen diverge from the designed one in the .pen — a gulf introduced by drift, not by the design?

Apply the hesitation test at every step: would a first-time user pause to ask "how do I do this?" or "did that work?" Each pause is a candidate. Confirm the gulf is real (a pattern, not one imagined user) before proposing a bridge.

2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/ux-review-<timestamp>.html so each run gets a fresh file. Open it for the user — xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows — and tell them the absolute path.

Each candidate gets a card with a before/after visualisation and a recommendation-strength badge; the report ends with a Top recommendation section. The full scaffold, candidate-card fields, diagram patterns, and styling live in JOURNEY-REPORT.md — follow it.

Use CONTEXT.md vocabulary for the domain, and LANGUAGE.md vocabulary for the experience. Talk about "the Job: return an item" and "the execution gulf at the payment step" — not "the confusing button" or "the bad onboarding."

EXPERIENCE.md conflicts: if a candidate contradicts the documented intended experience, only surface it when the friction is real enough to warrant revisiting that intent. Mark it clearly in the card (e.g. a warning callout: "contradicts EXPERIENCE.md §Onboarding — but worth reopening because…"). Don't list every theoretical change the doc rules out.

Do NOT design the bridge in detail yet. After the file is written, ask the user: "Which of these would you like to explore?"

3. Grilling loop

Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — the user's Job, exactly where the gulf opens, the shape of the bridge, which signifier or feedback or model change closes it, and which states the bridge must cover — empty, loading, error, success, plus the two most-forgotten: the precondition already satisfied (the step is a no-op this time — don't render it as pending) and the action in flight (show motion, not a static label).

Model the bridge in Pencil, held to impeccable's bar — don't describe it in prose. Experience is designed, not specified — once the bridge's shape is settled, build it as an actual .pen design (batch_design against the schema from get_editor_state), covering every state the grilling surfaced. Layer impeccable over the design for visual hierarchy, motion, accessibility, and edge states, so the bridge ships polished, not merely functional. Where the bridge's feedback moments can carry personality — acknowledgments, gestures, celebrations, waits, errors — hold them to DELIGHT.md. Then show the user a get_screenshot (one taken immediately after a large batch_design can render stale — re-take if it comes back empty). The deliverable is two things: the approved .pen design — the spec whatever implements designs in the project builds from — and a design decision record (DECISION-RECORD.md). Implementation is out of scope. When several bridge shapes are in play, design them as separate variants — see BRIDGE-DESIGN.md for the design-the-bridge-twice pattern (parallel sub-agents, real .pen frames, not written specs).

Side effects happen inline as decisions crystallize:

• Surfaced a genuinely new domain noun (a thing the business has — an Order, a Cart, a Subscription)? Add it to CONTEXT.md — the shared domain glossary — as a one-line entry: the term, then a sentence defining it in the domain's own words. Create the file lazily if it doesn't exist. This is the only reason a UX session touches CONTEXT.md.
• Named a new experience term (a Job, a flow, a state, a feel)? Add it to EXPERIENCE.md, mirroring CONTEXT.md's glossary format (**Term**: → a one- or two-sentence definition of what it IS → optional _Avoid_), grouped under Jobs / Flows & states / Feel. Never decisions or implementation. Human-approved, like any EXPERIENCE.md edit.
• Chose a bridge — or set one aside with a load-bearing reason? That's a decision, not vocabulary. Record it as a design decision record in designs/decisions/NNNN-slug.md, co-located with the .pen (DECISION-RECORD.md): the chosen bridge, the alternatives considered and why they lost (so a future review doesn't re-suggest them), and the behaviour the bridge commits the product to. This — not EXPERIENCE.md — is where "we considered X and set it aside" lives. Only the reusable vocabulary a decision introduces (a named state like "Armed") graduates into the EXPERIENCE.md glossary.

See BRIDGING.md for how to close a gulf safely given its type — execution vs evaluation tactics, and why a bridge removes the gulf rather than papering over it with help text.