# UX Review

> Use when reviewing a change set for user experience quality — traces user flows instead of code paths, validates that the implementation delivers the right experience against the goals doc's UX spec

- Skill: `gitkraken/ux-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gitkraken/ux-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitkraken/ux-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gitkraken (https://skillmd.com/u/gitkraken)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gitkraken/ux-review

---


# /ux-review - User Experience Review

Traces user flows end-to-end against the goals doc. Validates that the implementation delivers the right experience — not just that the code is correct, but that the user gets the outcome they expect in a way that feels right.

**Use `/deep-review` for the code-level merge gate. Use `/ux-review` for user flow validation. Different lenses.**

## Usage

```
/ux-review [target] --scope .work/dev/{id}/
```

- **`--scope <path>`** (required): Path to the dev folder containing `goals.md`. The goals doc is not optional for UX review — without it, there's no authoritative description of intended user experience to review against. If no goals doc exists, **stop and tell the user** to run `/dev-scope` first or provide the UX intent inline.
- No argument: review staged changes (`git diff --cached`)
- `all`: all uncommitted changes
- `branch`: changes vs base branch (`git diff main...HEAD`)
- `pr`: current PR changes (`gh pr diff`)
- `commit:SHA`: specific commit

## When to Use /ux-review vs /deep-review

| Skill          | Traces     | Finds                                                                                    |
| -------------- | ---------- | ---------------------------------------------------------------------------------------- |
| `/deep-review` | Code paths | Merge gate: goals alignment, completeness, validation (bugs via built-in `/code-review`) |
| `/ux-review`   | User flows | Dead ends, missing feedback, discoverability gaps, UX breaks                             |

Use both together for user-facing changes: `/deep-review` catches code-level issues, `/ux-review` catches experience-level issues.

## When to Skip

Not every change needs a UX review. Skip when:

- The change is purely internal (refactor, performance optimization, test infrastructure) with no user-facing surface
- The change is a one-line bug fix where the UX impact is obvious and contained
- There is no goals.md and the user confirms the change has no UX dimension

When in doubt, run it — a quick "no UX findings" is cheap, a shipped UX bug is not.

## Step 1: Gather Context

1. **Read the goals doc** at `{scope}/goals.md` — focus on the **User Experience** and **Success Criteria** sections. These are the spec you're reviewing against.
2. **Get the diff** using the target argument (same as `/deep-review`):
   - No argument: `git diff --cached`
   - `all`: `git diff HEAD`
   - `branch`: `git diff main...HEAD`
   - `pr`: `gh pr diff`
   - `commit:SHA`: `git show SHA`
3. **Read all modified files in full** — not just the diff hunks. Understand surrounding context for user-facing behavior.

## Step 2: Identify User-Facing Changes

For each change in the diff, determine:

- **What surface it appears on**: editor, tree view, webview, quick pick, status bar, notification, command palette, context menu, terminal
- **What triggers it**: user action (click, command, keybinding), automatic (on file open, on repo change), event-driven (timer, external)
- **What the user sees**: before, during, and after the change takes effect

Filter out changes with no user-facing surface — note them as "no UX impact" and move on.

## Step 3: Trace User Flows

Unlike `/deep-review` which traces code paths from the diff, trace **user paths**:

1. **Start from the goals doc's UX section** — this is the spec. The review checks the diff against it.
2. **Walk each flow end-to-end** — starting from the trigger described in goals.md through to completion. Note every point where the implementation diverges from the described experience.
3. **Check what's NOT in the diff** — missing implementations are UX bugs. If goals.md describes an error state and the diff doesn't handle it, that's a finding.

## Step 4: Evaluate Against Seven Lenses

Not every lens applies to every change — skip lenses that don't apply and say so.

### 1. Flow Delivery

Does the implementation actually deliver the user flow described in `goals.md`?

- **Happy path**: Walk through the expected flow step by step. Does each step in the goals doc have a corresponding implementation? Are there gaps where the user would hit a dead end?
- **Error paths**: What does the user see when things go wrong? Is the error actionable ("couldn't find remote -- check your network connection") or opaque ("operation failed")? Does the error leave the user in a recoverable state?
- **Edge cases**: What happens with empty states, first-time use, missing data, concurrent operations, large inputs? Check the edge cases listed in goals.md -- are they handled?
- **Entry/exit**: Does the flow start from the right place (command palette, context menu, button, automatic trigger)? When it ends, does the user land somewhere sensible?

### 2. Feedback & Responsiveness

Does the UI communicate what's happening at every stage?

- **Loading states**: Operations that take time (git commands, API calls, file parsing) -- does the user see progress, a spinner, or at minimum that something is happening? Silence longer than ~200ms needs feedback.
- **Success confirmation**: When an action completes, does the user know it worked? Not every action needs a toast -- sometimes the UI updating is confirmation enough. But destructive or irreversible actions need explicit confirmation.
- **Failure communication**: When something fails, is the failure visible where the user is looking? A logged error the user never sees is not feedback.
- **State transitions**: When the UI changes state (loading -> loaded, editing -> saved, collapsed -> expanded), are transitions smooth or jarring?

### 3. Discoverability

Can users find and understand this feature?

- **Location**: Is the feature accessible from the right surface? (command palette, context menu, view action, editor gutter, status bar -- wherever the user would naturally look for it)
- **Naming**: Do command names, menu labels, and tooltips use language the user thinks in? Avoid internal jargon. A user searching the command palette should find this with the words they'd naturally type.
- **First encounter**: If this is a new feature, how does a user learn it exists? Is there a walkthrough step, a what's new entry, a contextual hint?
- **Affordances**: Do interactive elements look interactive? Do disabled elements explain why they're disabled (via tooltip or contextual message)?

### 4. Consistency

Does it feel like GitLens?

- **Interaction patterns**: Does this feature follow the same patterns as similar existing features? If GitLens already has a way to do something analogous, this should work the same way unless there's a clear reason not to.
- **Terminology**: Does it use the same words GitLens uses elsewhere for the same concepts? (e.g., "repository" vs "repo", "stash" vs "shelf")
- **Visual language**: Icons, tree item structures, webview layouts, quick pick formats -- do they match existing GitLens conventions?
- **Behavior expectations**: If the user has learned how one GitLens feature works, does that knowledge transfer to this one?

### 5. Workflow Integration

Does it fit into how people actually work in VS Code?

- **Flow preservation**: Does the feature keep the user in their flow, or does it yank them out of context? A modal dialog when a notification would do, or a full view switch when an inline indicator would suffice -- these are flow breaks.
- **Reversibility**: Can the user undo or back out? Destructive actions need confirmation. Multi-step flows need a way to go back or cancel.
- **Composability**: Does the feature work well alongside other VS Code features and other GitLens features? Does it conflict with common keybindings, monopolize panels, or break expected multi-repo behavior?
- **Interruption cost**: If the user is in the middle of something else (editing, reviewing, rebasing), does this feature interrupt them? Does it steal focus?

### 6. Information Design

Is the right information presented at the right time?

- **Progressive disclosure**: Does the UI show the essential information first and let the user drill into details? Or does it dump everything at once?
- **Information hierarchy**: Is the most important information the most visually prominent? In tree views, hover details, webview panels -- does the eye go to what matters?
- **Density**: Is the information density appropriate for the context? Tree views should be scannable. Detail panels can be richer. Quick picks should be concise.
- **Empty states**: When there's no data to show, does the user see a helpful message, or a blank void? Empty states are opportunities to guide ("No stashes yet -- use `git stash` to save work in progress").

### 7. Accessibility

Can all users use this feature effectively?

- **Keyboard**: Can every interaction be performed via keyboard? Tab order logical? Custom interactive elements have keyboard handlers?
- **Screen reader**: Do elements have appropriate ARIA labels, roles, and states? Do dynamic updates use live regions?
- **Focus management**: After actions that change the UI (open/close panels, navigate lists), is focus placed somewhere sensible? Modals trap focus?
- **Contrast and theming**: Does the feature respect VS Code's theme? No hardcoded colors? Works in high contrast themes?

## Review Rules

- The goals doc's UX section is the spec — review against it, not your own UX preferences
- If the goals doc's UX section is incomplete, flag that as a finding, don't invent requirements
- Missing implementations of described user flows are UX bugs, not "future work"
- A technically correct feature that's undiscoverable is still a failure
- Do not evaluate code quality, performance internals, or test coverage — that's `/deep-review` and `/review`
- Do not evaluate visual design of webview CSS (layout, spacing, color) beyond theming compliance — that requires visual inspection of a running extension
- Do not run the extension or interact with it — this is a code-level review of user-facing behavior, not a manual QA pass

## Output Format

### Findings (ordered by severity)

For each finding include:

| Field          | Values                                                                                                   |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| **lens**       | flow delivery / feedback / discoverability / consistency / workflow / information design / accessibility |
| **severity**   | critical (blocks merge) / high (should fix) / medium (fix soon) / low (note)                             |
| **confidence** | confirmed / likely / low-confidence                                                                      |
| **location**   | file:line or user-facing surface (e.g., "Commit Graph context menu")                                     |

Then: **what the user experiences**, **what they should experience instead**, **suggested fix**.

### Example Finding

> **lens**: feedback | **severity**: high | **confidence**: confirmed
> **location**: `src/commands/git/push.ts:142` -> push command error path
>
> **Issue**: When push fails due to no upstream branch, the error is caught and logged but the user sees nothing -- no notification, no status bar update, no output channel message. The operation silently fails.
>
> **Expected**: The user should see an actionable notification: "No upstream branch set for {branch}. Set upstream?" with a button to run `git push --set-upstream`.
>
> **Fix**: Add a `window.showWarningMessage` in the `PushError.is(ex, 'noUpstream')` branch with an action button that runs the set-upstream command.

### Required Sections

1. **Findings** — ordered by severity, using the format above
2. **Flow walkthrough** — the end-to-end user flow as implemented, annotated with where it matches and diverges from goals.md
3. **Workflow impact summary** — which existing user workflows this change touches and how they're affected. A change doesn't exist in isolation — identify the broader workflows that pass through the modified surfaces (e.g., a push behavior change affects commit->push->PR, stash->branch->push, etc.). For each impacted workflow: name it, describe what changed from the user's perspective, and flag whether the change is neutral, improved, or degraded.
4. **What works well** — UX strengths worth calling out
5. **Open questions** — things that need manual testing (interactions you can't fully evaluate from code alone)
6. **Verdict** — one of:
   - **UX approved** — the experience matches the intent
   - **UX approved with follow-ups** — minor issues that don't block merge
   - **UX needs work before merge** — the experience diverges from goals.md in ways that matter

If no issues found, say so explicitly, then list **residual risks** and **open questions for manual testing**.