Plan Review — Experience Dimension
Overview
The experience-dimension reviewer for plan-review. Scores five sub-dimensions:
information hierarchy, state coverage, accessibility, DX ergonomics, and AI-slop
avoidance. UX and DX in one pass reflects that "user" and "developer" are both
human consumers of an interface — what differs is the surface (a screen vs an
API/CLI), not the rigor required. The skill produces scored findings paired
with concrete fixes the plan author can apply. Used by plan-review's orchestrator
in parallel with plan-review-architecture.
When to Use
- Invoked by
plan-review as one of its two parallel reviewers
- The user wants an experience pass on a plan without the architecture review
- A plan has been edited substantially in user-facing or API-facing areas
When NOT to Use
- The plan has no user-facing or developer-facing surface (pure internal job;
experience review will produce noise)
- The change is single-task and the experience implications are obvious
Process
Step 1: Pre-read
Goal: Identify the surfaces the plan touches.
Inputs: The plan file. Optionally: the spec, existing UI mockups, or API specs.
Actions:
- Read the spec and plan.
- Identify each user-facing or developer-facing surface in the plan: screens,
modals, error states, API endpoints, CLI flags, config keys, log lines, error
messages, docs.
- For each, note: who consumes this, in what context, with what level of
familiarity.
Output: A surfaces inventory: <surface> — <consumer> — <context>.
Step 2: Score the five sub-dimensions
Goal: 5 scores with cited findings.
Inputs: The plan and the surfaces inventory.
Actions: For each sub-dimension below, score 0-10 and write at least one
finding citing a plan task or section.
Information hierarchy (0-10)
- For each user-facing surface: does the plan name what's primary, secondary,
tertiary?
- Does the plan say what the user sees first?
- Score 10 = hierarchy is unambiguous from the plan.
- Score 5 = the plan describes what's on a screen but not what's emphasized.
- Score 0 = the plan lists features without ordering.
State coverage (0-10)
- For each surface: does the plan address loading, empty, error, partial,
and success states?
- Are state transitions named (what happens after submit, after timeout)?
- Score 10 = all five state types named per surface.
- Score 5 = success and error covered; loading/empty/partial assumed.
- Score 0 = only the success state is described.
Accessibility (0-10)
- Keyboard navigation paths named?
- Screen reader semantics specified (ARIA labels, headings)?
- Color/contrast not the only carrier of meaning?
- Localization/RTL support flagged where applicable?
- For non-UI surfaces: is the API/CLI usable by an automation that doesn't
have human eyes (parseable output, exit codes)?
- Score 10 = accessibility is named per surface, not assumed.
- Score 5 = some surfaces named, others assumed-accessible.
- Score 0 = accessibility is unmentioned and the plan visibly precludes it.
DX ergonomics (0-10)
- Error messages for developers: do they say what went wrong AND what to do?
- API/CLI: are arguments named in the convention of the project?
- Defaults: does the plan name them?
- Time-to-hello-world (TTHW): can a new developer get a working call with one
copy-paste?
- Score 10 = a developer hitting an error knows the next step from the message.
- Score 5 = errors are named but copy is generic ("Internal error").
- Score 0 = errors are uncategorized; debugging requires reading source.
AI-slop avoidance (0-10)
- Plan or surface copy doesn't use AI-cliché vocabulary (delve, crucial, robust,
comprehensive, multifaceted, leverage, harness, unlock, journey, magical,
seamless, world-class, 10x, pivotal).
- No emoji bullet decoration.
- No "Here's the kicker" or "let me break this down" phrasing in user-facing
text.
- Headings name the thing, not advertise the experience.
- Score 10 = copy reads as if a careful engineer wrote it.
- Score 5 = some slop in user-facing strings, otherwise OK.
- Score 0 = the plan reads like marketing.
Step 3: Rank findings as fixes
Same procedure as plan-review-architecture's Step 3. Tag each fix as
[Blocker], [Important], or [Nice-to-have]. Cite plan tasks.
A blocker in this dimension is typically: a state type entirely missing for a
user surface (e.g., no error state defined for a submit flow), or an accessibility
gap that would fail a basic audit.
Step 4: Write the experience report
Goal: Hand plan-review a clean, paste-ready report.
Actions: Produce a Markdown block:
## Experience review
- Information hierarchy: X/10 — <one-line justification>
- State coverage: X/10 — <one-line justification>
- Accessibility: X/10 — <one-line justification>
- DX ergonomics: X/10 — <one-line justification>
- AI-slop avoidance: X/10 — <one-line justification>
### Findings
- [Blocker] <finding>; fix: <fix>; cite: <task #>
- [Important] <finding>; fix: <fix>; cite: <task #>
- [Nice-to-have] <finding>; fix: <fix>; cite: <task #>
Output: The Markdown block.
Rationalizations
| Excuse |
Why it sounds reasonable |
Why it's wrong |
What to do instead |
| "Loading and empty states aren't worth flagging — they're obvious." |
Most components have default loading spinners and empty-message components, so the assumption is "the framework will handle it." |
"The framework will handle it" is what produces a UI where the empty state shows "No items found" with no explanation, no call to action, and no path forward. Defaults are not defaults of quality; they're defaults of existence. The plan needs to name what the empty state says, not just that one will appear. |
Score state coverage on whether the plan says what each state shows. If the plan is silent, score it 5 or below and write the finding. |
| "Accessibility is something we'll add later." |
Some accessibility work genuinely is post-MVP polish. |
"Later" almost never happens because by the time the feature ships, the structure that should have been keyboard-navigable, screen-reader-labeled, and color-independent has hardened. Retrofitting accessibility costs 5-10x more than building it right. |
Score accessibility on whether the plan names it per surface. "Form is keyboard-navigable; submit on Enter; errors announced via aria-live" takes one line in the plan. If the plan is silent, the implementation will be silent too. |
| "AI-slop is just style — it doesn't affect correctness." |
Word choice doesn't change whether code works. |
Slop in user-facing copy ("our magical, AI-powered…") signals to the user that the team didn't care enough to write the words a careful engineer would. It also signals to the next maintainer that the bar here is low. The bar set by copy carries through to the bar set by everything else. |
Flag every slop instance in the plan. The fix is one-word substitutions ("magical" → drop or replace with a concrete verb). The discipline is uniform across the codebase. |
| "DX error messages: 'Internal error' is fine for now." |
Internal errors do happen, and exposing internals is a security concern. |
"Internal error" in a developer-facing surface is the line that produces support tickets and Stack Overflow questions. The dev needs to know whether to retry, fix their input, contact support, or give up. "Internal error" answers none of those. |
Score DX ergonomics on whether each error tells the dev what to do next. Generic copy is a finding. Fix: write the action ("Retry in 30s" / "Check the input format at " / "Contact support@…"). |
| "Information hierarchy is a designer concern, not the plan's." |
The plan describes the work; the designer chooses the layout. |
This was true when designers and engineers worked sequentially with specs in between. It's no longer true at the speed plans are written and shipped. The plan that doesn't name what's primary on a surface delegates the call to whoever implements first — and they will pick what's easiest, not what's best. |
Score hierarchy on whether the plan says what the user sees first per surface. If the plan names "modal with three tabs" without saying which tab is the default, that's a finding. |
Evidence Requirements
| Checkpoint |
Required artifact |
What "no evidence" looks like |
| End of Step 1 |
A surfaces inventory: <surface> — <consumer> — <context> |
"It's a UI plan." |
| End of Step 2 |
Five scores 0-10 each paired with at least one cited finding |
"UX is good; DX has some gaps." |
| End of Step 3 |
Ranked fix list with [Blocker/Important/Nice] tags |
"Some things to improve." |
| End of Step 4 |
The Markdown block in the exact format above |
A free-form summary. |
Red Flags
- Sub-dimension 5 (AI-slop) scores 10 but the plan contains words like "leverage,"
"seamless," or "delightful." You missed instances; re-read.
- Information hierarchy scores 10 on a plan with no UI mockup, no wireframe, and
no copy specified. You're guessing.
- DX score is 10 on a plan with no API surface. The dimension doesn't apply; mark
it
n/a rather than scoring 10.
- All findings are AI-slop. The reviewer is fixated on copy and missed the
structural issues.
- The plan has zero error states named and the score is above 5. Re-score.
References
- Steve Krug, Don't Make Me Think (New Riders, 3rd ed. 2014), Chapter 1
"Don't make me think!" — the principle of obviousness operationalizes into the
information-hierarchy and state-coverage sub-dimensions.
- Web Content Accessibility Guidelines (WCAG) 2.1 (W3C, 2018) — the citation
standard for sub-dimension 3 (accessibility). Use AA as the default conformance
level when scoring.
1---2name: plan-review-experience3description: Experience-dimension reviewer for written plans (UX + DX). Use when running plan-review or directly when an experience review is wanted. Activate for keywords like "UX review", "DX review", "experience review", "error states", "API ergonomics", "developer experience", "user states". Scores 5 sub-dimensions 0-10 covering both end-user experience (information hierarchy, state coverage, accessibility) and developer experience (error copy, API/CLI ergonomics, AI-slop avoidance). Always cite plan task numbers -- never write generic UX/DX advice.4---56# Plan Review — Experience Dimension78## Overview910The experience-dimension reviewer for `plan-review`. Scores five sub-dimensions:11information hierarchy, state coverage, accessibility, DX ergonomics, and AI-slop12avoidance. UX and DX in one pass reflects that "user" and "developer" are both13human consumers of an interface — what differs is the surface (a screen vs an14API/CLI), not the rigor required. The skill produces scored findings paired15with concrete fixes the plan author can apply. Used by `plan-review`'s orchestrator16in parallel with `plan-review-architecture`.1718## When to Use1920- Invoked by `plan-review` as one of its two parallel reviewers21- The user wants an experience pass on a plan without the architecture review22- A plan has been edited substantially in user-facing or API-facing areas2324## When NOT to Use2526- The plan has no user-facing or developer-facing surface (pure internal job;27 experience review will produce noise)28- The change is single-task and the experience implications are obvious2930## Process3132### Step 1: Pre-read3334**Goal:** Identify the surfaces the plan touches.3536**Inputs:** The plan file. Optionally: the spec, existing UI mockups, or API specs.3738**Actions:**39401. Read the spec and plan.412. Identify each user-facing or developer-facing surface in the plan: screens,42 modals, error states, API endpoints, CLI flags, config keys, log lines, error43 messages, docs.443. For each, note: who consumes this, in what context, with what level of45 familiarity.4647**Output:** A surfaces inventory: `<surface> — <consumer> — <context>`.4849### Step 2: Score the five sub-dimensions5051**Goal:** 5 scores with cited findings.5253**Inputs:** The plan and the surfaces inventory.5455**Actions:** For each sub-dimension below, score 0-10 and write at least one56finding citing a plan task or section.57581. **Information hierarchy (0-10)**59 - For each user-facing surface: does the plan name what's primary, secondary,60 tertiary?61 - Does the plan say what the user sees first?62 - Score 10 = hierarchy is unambiguous from the plan.63 - Score 5 = the plan describes what's *on* a screen but not what's emphasized.64 - Score 0 = the plan lists features without ordering.65662. **State coverage (0-10)**67 - For each surface: does the plan address loading, empty, error, partial,68 and success states?69 - Are state transitions named (what happens after submit, after timeout)?70 - Score 10 = all five state types named per surface.71 - Score 5 = success and error covered; loading/empty/partial assumed.72 - Score 0 = only the success state is described.73743. **Accessibility (0-10)**75 - Keyboard navigation paths named?76 - Screen reader semantics specified (ARIA labels, headings)?77 - Color/contrast not the only carrier of meaning?78 - Localization/RTL support flagged where applicable?79 - For non-UI surfaces: is the API/CLI usable by an automation that doesn't80 have human eyes (parseable output, exit codes)?81 - Score 10 = accessibility is named per surface, not assumed.82 - Score 5 = some surfaces named, others assumed-accessible.83 - Score 0 = accessibility is unmentioned and the plan visibly precludes it.84854. **DX ergonomics (0-10)**86 - Error messages for developers: do they say what went wrong AND what to do?87 - API/CLI: are arguments named in the convention of the project?88 - Defaults: does the plan name them?89 - Time-to-hello-world (TTHW): can a new developer get a working call with one90 copy-paste?91 - Score 10 = a developer hitting an error knows the next step from the message.92 - Score 5 = errors are named but copy is generic ("Internal error").93 - Score 0 = errors are uncategorized; debugging requires reading source.94955. **AI-slop avoidance (0-10)**96 - Plan or surface copy doesn't use AI-cliché vocabulary (delve, crucial, robust,97 comprehensive, multifaceted, leverage, harness, unlock, journey, magical,98 seamless, world-class, 10x, pivotal).99 - No emoji bullet decoration.100 - No "Here's the kicker" or "let me break this down" phrasing in user-facing101 text.102 - Headings name the thing, not advertise the experience.103 - Score 10 = copy reads as if a careful engineer wrote it.104 - Score 5 = some slop in user-facing strings, otherwise OK.105 - Score 0 = the plan reads like marketing.106107### Step 3: Rank findings as fixes108109Same procedure as `plan-review-architecture`'s Step 3. Tag each fix as110`[Blocker]`, `[Important]`, or `[Nice-to-have]`. Cite plan tasks.111112A blocker in this dimension is typically: a state type entirely missing for a113user surface (e.g., no error state defined for a submit flow), or an accessibility114gap that would fail a basic audit.115116### Step 4: Write the experience report117118**Goal:** Hand `plan-review` a clean, paste-ready report.119120**Actions:** Produce a Markdown block:121122```markdown123## Experience review124125- Information hierarchy: X/10 — <one-line justification>126- State coverage: X/10 — <one-line justification>127- Accessibility: X/10 — <one-line justification>128- DX ergonomics: X/10 — <one-line justification>129- AI-slop avoidance: X/10 — <one-line justification>130131### Findings132133- [Blocker] <finding>; fix: <fix>; cite: <task #>134- [Important] <finding>; fix: <fix>; cite: <task #>135- [Nice-to-have] <finding>; fix: <fix>; cite: <task #>136```137138**Output:** The Markdown block.139140## Rationalizations141142| Excuse | Why it sounds reasonable | Why it's wrong | What to do instead |143|---|---|---|---|144| "Loading and empty states aren't worth flagging — they're obvious." | Most components have default loading spinners and empty-message components, so the assumption is "the framework will handle it." | "The framework will handle it" is what produces a UI where the empty state shows "No items found" with no explanation, no call to action, and no path forward. Defaults are not defaults of *quality*; they're defaults of *existence*. The plan needs to name what the empty state says, not just that one will appear. | Score state coverage on whether the plan *says* what each state shows. If the plan is silent, score it 5 or below and write the finding. |145| "Accessibility is something we'll add later." | Some accessibility work genuinely is post-MVP polish. | "Later" almost never happens because by the time the feature ships, the structure that should have been keyboard-navigable, screen-reader-labeled, and color-independent has hardened. Retrofitting accessibility costs 5-10x more than building it right. | Score accessibility on whether the plan *names* it per surface. "Form is keyboard-navigable; submit on Enter; errors announced via aria-live" takes one line in the plan. If the plan is silent, the implementation will be silent too. |146| "AI-slop is just style — it doesn't affect correctness." | Word choice doesn't change whether code works. | Slop in user-facing copy ("our magical, AI-powered…") signals to the user that the team didn't care enough to write the words a careful engineer would. It also signals to the next maintainer that the bar here is low. The bar set by copy carries through to the bar set by everything else. | Flag every slop instance in the plan. The fix is one-word substitutions ("magical" → drop or replace with a concrete verb). The discipline is uniform across the codebase. |147| "DX error messages: 'Internal error' is fine for now." | Internal errors do happen, and exposing internals is a security concern. | "Internal error" in a developer-facing surface is the line that produces support tickets and Stack Overflow questions. The dev needs to know whether to retry, fix their input, contact support, or give up. "Internal error" answers none of those. | Score DX ergonomics on whether each error tells the dev what to do next. Generic copy is a finding. Fix: write the action ("Retry in 30s" / "Check the input format at <doc-link>" / "Contact support@…"). |148| "Information hierarchy is a designer concern, not the plan's." | The plan describes the work; the designer chooses the layout. | This was true when designers and engineers worked sequentially with specs in between. It's no longer true at the speed plans are written and shipped. The plan that doesn't name what's primary on a surface delegates the call to whoever implements first — and they will pick what's easiest, not what's best. | Score hierarchy on whether the plan says what the user sees first per surface. If the plan names "modal with three tabs" without saying which tab is the default, that's a finding. |149150## Evidence Requirements151152| Checkpoint | Required artifact | What "no evidence" looks like |153|---|---|---|154| End of Step 1 | A surfaces inventory: `<surface> — <consumer> — <context>` | "It's a UI plan." |155| End of Step 2 | Five scores 0-10 each paired with at least one cited finding | "UX is good; DX has some gaps." |156| End of Step 3 | Ranked fix list with `[Blocker/Important/Nice]` tags | "Some things to improve." |157| End of Step 4 | The Markdown block in the exact format above | A free-form summary. |158159## Red Flags160161- Sub-dimension 5 (AI-slop) scores 10 but the plan contains words like "leverage,"162 "seamless," or "delightful." You missed instances; re-read.163- Information hierarchy scores 10 on a plan with no UI mockup, no wireframe, and164 no copy specified. You're guessing.165- DX score is 10 on a plan with no API surface. The dimension doesn't apply; mark166 it `n/a` rather than scoring 10.167- All findings are AI-slop. The reviewer is fixated on copy and missed the168 structural issues.169- The plan has zero error states named and the score is above 5. Re-score.170171## References172173- Steve Krug, *Don't Make Me Think* (New Riders, 3rd ed. 2014), Chapter 1174 "Don't make me think!" — the principle of obviousness operationalizes into the175 information-hierarchy and state-coverage sub-dimensions.176- *Web Content Accessibility Guidelines (WCAG) 2.1* (W3C, 2018) — the citation177 standard for sub-dimension 3 (accessibility). Use AA as the default conformance178 level when scoring.
duthaho