User Behavior Flow — what the user sees, does, and gets, before code

Design-to-delivery integration

For complex feature/screen design, consider design-to-delivery: an Excalidraw flow in docs/diagrams/ can guide brainstorming, behavior detail in docs/specs/<work-id>/specs.md or linked existing USER-FLOW.md, and tasks in docs/task/<work-id>/tasks.md. This recommended sequence helps catch missing states and inconsistent transitions. Adapt the order, reuse existing documents or omit optional artifacts when a simpler method fits. A diagram is not mandatory merely because this skill is loaded. Preserve prior documents and honor explicitly requested deliverables/timing.

Purpose

Turn "we need a feature/screen for X" into an explicit user-behavior spec — every step the user takes, what's on screen, what they can interact with, and what comes back — before or while building the UI. The pair to api-behavior-flow: that skill fixes the machine's behavior, this one fixes the human's. Both together prevent the classic failure of building screens whose happy path works and whose error states are invented mid-crisis.

Works in two modes:

• Design-first (new feature): write the spec, confirm ambiguous UX decisions with the user, then implement.
• Retro-map (existing feature): extract the behavior from code, flag states that are missing or inconsistent.

When to use

• Designing a new frontend feature, screen, or multi-step journey (forms, onboarding, checkout, wizards).
• User asks what the user sees/does at each step, or what happens when the user does X.
• Before implementing anything with states beyond "loaded" — async mutations, payments, multi-role visibility, RTL-first flows.
• Trigger phrases include: "رفتار کاربر رو دربیار", "کاربر کجا چی کلیک می‌کنه", "قبل از ساخت بگو کاربر چی می‌بینه", "map the journey first", "what does the user see if the request fails".

Preconditions

• You know the feature's scope and which app it lives in (framework irrelevant to the method). Existing design system, component library, i18n/RTL setup: infer from the repo.
• If the feature calls an API that doesn't exist yet, run api-behavior-flow for it first (or in parallel) — user-flow error states must reference real API error branches, not guessed ones.
• For retro-mapping many screens, delegate per-screen reading to Explore subagents (same partitioning as behavior-audit).

Workflow

1. Scope the journey (main agent — cheap reads): routes, layout/shell, existing component library, state management convention, how the app currently handles loading and errors (toast? inline? full page?). New screens must match these conventions.
2. Define the actors and entries. Who uses this feature (roles/permissions — what does each role see)? Every entry point: nav, deep link, button elsewhere, notification. Every exit point: where does the user land when done or when abandoning?
3. Walk the happy path step by step — this exact shape per step:

   • Screen state: what's rendered (components, data shown, primary action).
   • User actions: every control they can touch and what it triggers.
   • System response: what happens — optimistic update? spinner? navigation? Which API call fires (name the endpoint)?
   • Next state: where the user lands.

4. Branch every step. For each step with any async or decision behavior, list: loading state · failure state (mapped to the API's actual error branches — "invalid input", "unauthorized", "rate limited", "server error" each get explicit UI: message, placement, what the user can do next) · empty/first-use state · permission denied / role-variant state · edge inputs (double-click, back button mid-flow, refresh mid-flow, offline). This is the core of the skill — a step without its failure state isn't finished.
5. Write USER-FLOW.md (repo root or the project's docs convention):
   • Header: scope, date, actors, entry/exit points.
   • Journey-level mermaid flowchart (nodes = screens/states, branches = user choices and failures).
   • One section per step in the step-3/4 shape; state table (state × what's shown × what's possible) for screens with many parallel states.
   • Open questions section at top: UX decisions only the user can make (copy, funnel order, what happens after success), phrased as either/or.
   • UX notes: confusing-step risks, missing feedback risks, first-use tip spots.
   • Dense bullets; no prose paragraphs. Diagrams (when asked): excalidraw skill.
6. Resolve blocking questions, then implement when requested. Batch genuinely unresolved UX decisions, infer safe choices from existing patterns, and do not ask for fresh approval when implementation is already authorized. Mapping-only requests deliver the map without edits. Fold answers into the steps. Implementation then follows the spec: every listed state gets a real component state (no "TODO: error handling"), and visible text follows the project's language rules (Persian UI copy stays RTL-complete — mirrored layout, mirrored icons, per Design Standards in global AGENTS.md). Keep USER-FLOW.md in sync when the flow changes later.

Rules

• Evaluate all five states for every async step: loading, success, failure, empty, permission-denied. Describe applicable states and mark genuinely irrelevant ones N/A with a reason; a local action need not invent an API or permission state.
• Error states reference real error sources — the API's error model or the platform's (offline, camera denied), never a generic "something went wrong" placeholder.
• Keep action hierarchy clear. Prefer one primary action per task context; multiple equivalent actions can be valid in a workspace. Follow existing product patterns instead of forcing a funnel or asking about every routine button.
• Name the real data source per step: API endpoint, local state, file or platform event. Unknown sources are explicit open questions; do not invent an endpoint for a local interaction.
• Describe behavior, not components' internals — the spec survives refactors.
• Visual decisions (tokens, spacing, motion) are not this skill's output — they follow the project design system and Design Standards; this skill specifies behavior.

Common mistakes

• Specifying the happy path only, then inventing error handling live in the PR.
• "Loading…" for every async action without deciding where the loading appears (button spinner? skeleton? full page?).
• Forgetting mid-flow navigation: back button, refresh, deep link into step 3 of a wizard.
• Letting the spec drift into visual design instead of behavior.
• Writing it after the UI is built — then it's a retro-map; still useful, but say so.

Verification

• Walk the spec top to bottom as the user: every click listed has a response and a next state; no dead ends.
• Every step with an API call maps each of that endpoint's error branches to a UI state.
• All applicable states are specified; N/A states have a reason and empty states have first-use copy direction.
• Every open question is answered (and folded in) or visibly pending.
• If implemented: click through the journey in the running app and check each specified state exists — or have web-gui-tester do it.