Skip to main content
The ux-flow-specification skill produces a complete behavioral specification for how a user moves through a product — covering information architecture, user journeys, every screen in the flow, and every state each screen can be in. It deliberately separates behavior and structure from visual styling: specifying “after a failed payment, the user sees an inline error on the same screen with the amount preserved and a retry button” rather than what color that error is. Visual language belongs in design-system-specification; this document governs behavior.
This skill is conditional. If the project is a pure backend service, a CLI tool with no user-facing screens, or a data pipeline with no interactive UI, skip this skill and proceed to design-system-specification (also conditional) or admin-access-control-specification.

​
Best for

  • Mapping the full user journey through a product or major new feature before implementation begins
  • Defining the information architecture and navigation structure of an application
  • Specifying every UI state (loading, empty, error, success, permission-denied) so none are left to improvisation during build
  • Giving an AI coding agent or new engineer enough detail to build every screen without a visual mockup

​
What it produces

The generated document covers:
  1. Overview — which flow(s) the document covers, primary tasks served
  2. Information architecture — site map (ASCII or structured list) of every screen and nesting relationship
  3. User journeys — end-to-end narrative for each primary task, including cross-session and multi-channel steps
  4. Screen-by-screen flow — for each screen: entry points, primary action, all four states (loading / empty / error / success), and every exit point
  5. Flow diagram — Mermaid flowchart showing the primary path, branching decision points, error branches, and recovery loops
  6. Responsive behavior — layout changes per breakpoint (desktop / tablet / mobile), hidden elements, touch adaptations, cross-device state continuity
  7. Error taxonomy — per error type: example scenario, user message pattern, recovery action
  8. Confirmation patterns — when to use a modal vs. an undo toast vs. double confirmation for catastrophic actions
  9. Notification patterns — toast, banner, in-app notification, inline message: use case, duration, dismissability, position
  10. State management — form persistence, undo support, offline behavior, stale data handling
  11. Edge cases and recovery paths — table of every non-happy-path scenario with trigger, behavior, and recovery (no dead ends)
  12. Accessibility notes — per-screen keyboard/tab order, focus management after actions, “completable without mouse” verification

​
How to invoke it

Include known edge cases when invoking: “handle expired verification code, wrong code entry, and a user who already has an account.” The richer the edge case list, the more complete the recovery path section.

​
Example scenarios

Onboarding flow

“Document the user flow for account signup through first successful login — email verification, password set, empty-state dashboard, including expired code and existing account cases.”

Dashboard IA

“Map the information architecture and navigation structure for our merchant analytics dashboard.”

Checkout flow

“Specify every screen and state needed for the checkout flow — payment entry, processing, success, and all failure modes.”

Settings and permissions

“Document the settings and access-management flow — role assignment, invitation, permission-denied states.”

​
Key concepts

A screen is not complete until all four states are described. Omitting any one is the single most common source of “the happy path works but everything else is undefined” bugs:
Information architecture (IA): The structural map of every screen/page and how they nest or relate — the site map. Answers “where does this screen live” independent of any single task.User journey: The end-to-end narrative of accomplishing a goal, possibly crossing sessions or channels. Big-picture context.Screen flow: The literal sequence of screens and user actions for one specific task. Implementation-level precision. The skill produces all three.
  • Destructive, irreversible actions: Blocking confirmation modal with the action name and consequence stated (“Delete payment link — this cannot be undone”)
  • Reversible actions: Prefer undo toast (toast with “Undo” button, 5–10 second auto-dismiss) over a blocking dialog — less friction, same safety
  • Catastrophic actions (delete organization, revoke all access): Require the user to type the resource name — double confirmation
  • Confirmation placement: Inline for minor actions, modal for significant actions, full-page for account-level changes
Accessibility is not just visual — it is structural and must be specified per screen:
  • Keyboard tab order: The sequence focus moves through interactive elements on each screen
  • Focus management after actions: Where does focus land after a modal closes? After form submission? After an error?
  • Completable without mouse: Every screen flow must be traversable via keyboard alone — specified in the accessibility notes table
A screen with no way to go back, forward, or recover is a UX defect to catch at spec time. Every screen must have explicit exit points for every state, including error states. The edge cases table explicitly flags any scenario that would result in a dead end and documents the recovery path.
For products used across devices, the spec documents:
  • Breakpoint behavior: What elements collapse, hide, or reflow at each breakpoint (desktop / tablet / mobile)
  • Touch vs. pointer: Hover states that become tap-and-hold, swipe replacing click-and-drag
  • Context-aware defaults: Which actions are prominent on mobile vs. desktop
  • Cross-device continuity: What state is preserved if a user switches devices mid-flow

​
Interview process

1

Phase 1: Socratic clarification (mandatory)

Reads all prior .engineering-docs/ files first. Up to 3 questions: primary task (the single most important thing a user is trying to accomplish), and known edge cases (failure modes, permission levels, unusual paths that must be handled).
2

Phase 2: Information architecture (60 min)

Map every screen/page and how they nest or link. Produce the site map.
3

Phase 3: User journey mapping (40–60 min)

Narrate end-to-end journeys for the primary tasks, including any cross-session or multi-channel steps.
4

Phase 4: Screen-by-screen flow (2–3 hrs)

For each screen: entry point, primary action, all four states, and every exit/navigation option.
5

Phase 5: Edge cases and recovery paths (40–60 min)

Walk through every known failure mode and unusual path. Ensure none result in a dead end.
6

Phase 6: Accessibility pass (30–40 min)

Verify keyboard navigation order, focus management, and that the flow is completable without a mouse.
7

Phase 7: Revision (after user review)

Apply changes, check for cross-document conflicts, update last_updated.

​
Output structure

The generated .engineering-docs/10-ux-flow-specification.md follows this structure:
Target length: 5–10 pages excluding appendices.

​
Handoff

Reads from

  • 3-user-personas.md — persona goals, journey context, friction tolerance
  • 1-business-plan.md — scope, feature priorities, user types
  • 4-technical-specification.md — functional requirements defining screen behavior

Feeds into

  • design-system-specification — component needs, interaction patterns, state requirements
  • system-architecture-document — frontend component structure, API interaction points
  • Implementation — screen-by-screen build specification for engineers and AI agents

​
Quality gate

  • Every screen in the flow specifies all four states: loading, empty, error, and populated/success
  • No screen is a dead end — every screen has explicit exit points including for error states
  • The information architecture (site map) is complete and every screen in the flow appears in it
  • Edge cases and recovery paths are documented in a table with no scenario resulting in an unrecoverable state
  • Each screen includes accessibility notes covering keyboard navigation order and focus management
Common gotchas:
  • Specifying only the happy path — missing states (loading, empty, error) are the most common UX defect
  • Creating dead-end screens — every screen must have a way forward, back, or to recover
  • Confusing this document with visual design — “the error is red” belongs in design-system-specification; this document says “an inline error message appears with the field value preserved and a retry action”
  • Forgetting accessibility as a flow concern — keyboard tab order and focus management are structural decisions, not visual polish
  • Not cross-referencing personas — a flow that doesn’t connect to the defined user goals risks optimizing for the wrong user