authoring-user-flows

authoring-user-flows — SKILL.md

Variant: standard · When to use: a producer is authoring (or amending) the user-flows document for a product/feature and needs the derivation method + the production-grade bar (walkability + structure + resilience + accessibility + quality + amend), composing the section structure from a separate template tool.

Overview

This skill guides authoring a user-flows document: the navigation/interaction graph of a product — where users enter, the IA frame the flows live in, the happy path they walk, where the path forks, the screens/states they pass through, what happens when things go wrong, whether the path is resilient and accessible, and whether it is a good flow. It carries the judgment (how to derive flows from upstream goals + prior art instead of inventing them, how to make sure no path dead-ends, how to keep a diagram and narrative in sync, how to amend without redrawing), not a section list — the structure comes from a template tool. The document sits below an approved PRD (which supplies the goals + personas) and above wireframing (every screen a flow names becomes a wireframe target). Scope is the interaction graph, not pixels, not the PRD's product decisions, and not a journey map (emotion/channel/touchpoint-over-time is out of scope).

When to activate

Authoring a user-flows / task-flow / interaction-flow document for a product or feature, given an approved PRD with goals + personas.
Amending an existing user-flows doc with a scoped change (add/change/remove a flow or path) — a versioned delta, not a regenerate (see Step 11).
Mapping the paths (entry → steps → branches → error/recovery → exit) a user takes, so a downstream wireframing pass can enumerate every screen.

Do NOT activate when:

Reviewing/judging a finished user-flows doc — that is the review-side gate (reviewing-user-flows), which asserts the same bar this skill produces to.
Designing screen layout / pixels — that is authoring-wireframes, which consumes these flows. Per-screen pixel accessibility (contrast/target-size) is also theirs.
Authoring the upstream PRD itself, or re-deciding the product goals/personas.
Producing a user journey (emotion/channel/over-time) — a different artifact.

Inputs

Read every document the plan hands you — your depends_on set (the upstream documents discovery determined inform this one) — and trace this document's content back to them. The typical upstream is the PRD (goals + personas); a design system (if one exists) supplies the navigation/app-shell + component vocabulary the flows reference; when amending, the existing user-flows doc is handed in as an input. Do not assume a fixed input: the named upstreams are guidance, not a cap. Be self-contained — produce from whatever context you actually receive; when an expected informing document is absent, proceed on what you have and surface the gap as an explicit assumption, never fabricate to fill it. And use a research capability where one is available (deep-research) to ground domain conventions + prior-art flow patterns, not merely to fill the template.

Capability context (when provided): If a capability_record (a record from capability-map.yaml product_capabilities) is injected by the caller, read it before Step 1. It defines your scope boundary: owns = entities you cover; refs = entities you reference but do not own; publishes/consumes = events you surface; entry_points/exit_points = how users arrive and leave; has_ui/has_api/has_persistence = which surfaces apply. When present, treat it as a hard constraint — do not stray outside the boundary it defines.

Workflow

Compose with the template tool first. Before drafting, obtain the user-flows section structure from the content-template tool (the content-template-gateway capability, or whatever template provider is installed). It supplies the per-flow slots (goal/PRD tie-back, entry points, flowchart, narrative, branches, error/ recovery, resilience & system-status, accessibility, screens/states, success), plus the Navigation & IA, cross-flow transition, screens-index, assumptions, and versioning/changelog sections. Never hardcode a competing outline — this skill fills the template's slots with derived content; it does not redefine them.

If ALL capability records are injected: map cross-capability journeys using exit_points → entry_points chains. Label each flow with the capability IDs it traverses. Per-capability flows stay within the capability's entry_points/exit_points.

Step 1: Derive one flow per goal/persona — frame as a job, ground in prior art

Treat each PRD goal as a job the persona is getting done (the goal in their words, with its functional/social context), and produce one flow per goal/persona pairing. Different personas may approach the same goal differently — give each its own flow, and state why they diverge (mental model / context), rather than collapsing them. This is the no-orphan guarantee: every PRD goal/persona ends up with a flow, and every flow points back to one. Ground each flow in the established interaction pattern for its job (standard auth / password-reset / checkout / onboarding / OAuth) and the product's prior art — don't reinvent a solved flow; deviate only with a stated reason. Fill the coverage map with that mapping first; it is the spine the rest hangs on. Keep the doc a flow, not a journey — no emotion/channel per step.

Step 2: Map the navigation & IA frame

Before drawing individual paths, establish the structural frame they live in (fill proportionally — a single-screen tool collapses most of this):

Entry-point taxonomy — every door (homepage, deep link, email/invite, notification, campaign), and the state each entry lands in (a deep-linked user may skip steps).
Navigation / app-shell model + wayfinding — the persistent chrome the flows run within, where each flow sits in the IA, and how the user always gets back to a known place (never trapped away from the shell). Reference the design system's shell if one exists.
Deep-linking / routing — for a routable product: the routes traversed + the prereq-missing guard/resume (deep-link into a state that needs prior steps → interstitial → resume).
Cross-device divergence — where a path (not just layout) differs by form factor (an extra mobile step, a native sub-flow).

Step 3: Map the happy path first

For each flow, lay down the critical path most users follow — entry → ordered steps → the success exit — in plain language, no errors yet. Name every screen/state each step traverses with a stable name you reuse verbatim in the diagram, narrative, and index. Layer complexity onto this skeleton; do not start from the edge cases.

Step 4: Enumerate every decision branch

At each point where the user can go more than one way, name all outgoing branches and resolve each to a step, another flow, or a clean exit. A decision with one side unmapped is the gap that surfaces late in build. No dangling "Yes/No" with a missing arm. Where flows hand off to each other, record the hand-off in the cross-flow transitions section and confirm the target flow exists (no hand-off to an undefined or removed flow).

Step 5: Walk the edge-case checklist + the states — no dead ends

Walk this fixed checklist at each step so coverage is systematic, not inspirational — and treat the states as nodes the path traverses (they become wireframe targets):

Empty / null · invalid + extreme inputs (boundary 0/1/max/max+1) · timeout / network / integration errors · interruption / session loss · permission / auth denial · back / cancel.
Loading / in-progress states — every async/slow step passes through one (skeleton / spinner / progress); draw it (an async step = trigger → in-progress → success | error), so it lands in the screens index.
Success / confirmation states — the concrete "goal accomplished" state the user sees (confirmation screen / reference / receipt), not just an abstract "success".

For each applicable case give the user a state and a recovery path back to a productive step — never strand them. Every error state says what went wrong AND how to fix it.

Step 6: Add interaction resilience & system-status

Beyond error-recovery, make the path resilient (fill where applicable; see references/resilience-and-states.md for depth):

Undo / confirm-on-irreversible — every destructive or irreversible action (delete / pay / send / final submit) carries a confirm or an undo; reversible actions prefer undo over a modal confirm.
Resume vs restart — each multi-step flow states its interruption behavior (what persists, for how long) — not a silent discard on reload.
"What changed" feedback — each state-changing step shows its result, not just "done" (saved as draft, $X authorized, submitted as #1234).
Optimistic vs confirmed — for an async action, state the stance; optimism is for low-risk only (never payments/deletes) and must define the revert + feedback on failure.

Step 7: Check flow-level accessibility

Ensure every persona, including assistive-tech users, can complete each path (see references/flow-accessibility.md). This is flow-level a11y, NOT per-screen pixel WCAG (that is wireframes/design-system):

Keyboard-completable end to end, no trap.
Focus order on step/route change (WCAG 2.2 SC 2.4.3) — focus moves in a meaning-preserving order; on a step/route change it moves to the new content, not dropped.
AT-completability of every path — happy and unhappy; errors are announced (programmatically determinable), not color/position-only.
No mouse-only / gesture-only required step (each has a keyboard equivalent).

Step 8: Apply the objective flow-quality heuristics

Make it a good flow, not only a complete one — the objectively checkable subset (subjective taste is out of scope; see references/flow-quality.md):

Error prevention over recovery — guard an irreversible action before it happens (confirm / preview / validate-before-enable), not only recover after.
Recognition over recall — a step surfaces what a prior step established; no "remember the code from screen 2 and type it on screen 4" without carry-forward.
No gratuitous step — the path is no longer than the job needs (path-length is judged here, once — not in accessibility).
Consistency — like jobs use like paths across the flows; follow platform/DS conventions or state the deviation.

Step 9: Render both notations, kept in sync

Render each flow twice: a Mermaid flowchart (terminals for start/end, rectangles for screens/states, diamonds for decisions, labelled edges) and a numbered narrative plus an explicit branch/error-path list. For a multi-actor flow (user ⇄ system ⇄ admin, a third-party provider, an approval hand-off), use swimlanes (Mermaid subgraph per actor) so who-does-what is explicit. The two notations must describe the same graph — a node/branch in one but not the other is a defect. Specify the message intent of load-bearing states (error = cause+fix, empty = guide-to-action, success = the result), and use one canonical name per screen across diagram/narrative/index.

Step 10: Surface thin-PRD gaps as assumptions / open questions

Where the PRD did not specify something a flow needs, state the assumption (so a reviewer can challenge it) and list any unresolved decision as an open question — never silently invent a product decision and bury it inside a flow. Keep journey-only content (emotion/channel) out — lift it to an upstream reference if genuinely needed.

Step 11: When amending — scope the ripple, edit don't redraw, version the doc

When handed an existing user-flows doc + a scoped change, treat it like versioned source code (see references/amend-method.md):

Scope the ripple — which flow(s)/branch(es)/path(s) the change touches, AND the ripple: cross-flow hand-offs into a changed/removed flow, screens-index entries a removed path referenced, branch targets that moved.
Edit, don't redraw — minimal in-place edit; untouched flows (diagrams, narratives, index rows) stay byte-for-byte unchanged. No gratuitous re-numbering.
Version + changelog — bump the doc's own version (MAJOR = removed/renamed flow or removed reachable path; MINOR = added flow/branch/path; PATCH = wording/ notation), add a Keep-a-Changelog entry at flow/path grain.
Deprecate safely — deprecate a flow/path in a MINOR (mark + name the replacement) before removing in a MAJOR; when a screen leaves, prune the index and confirm no remaining path references it.

Step 12: Self-check against the bar (below) before handoff

Run the quality bar. Fix every miss before handing the document to review or to wireframing.

Rules

Hard rules (never violate):

Compose, don't duplicate. The section structure comes from the template tool; this skill never ships a competing outline.
Derive, don't invent — both directions. Every flow traces to a PRD goal/persona; every PRD goal/persona has a flow; standard flows follow their established pattern or state the deviation. No orphans, no reinvented-solved-flow.
No dead ends. Every decision branch resolves, and every error/edge state has a recovery path back to a productive step.
Both notations, in sync. Each flow has a Mermaid flowchart AND a numbered narrative + branch/error list describing the same graph; swimlanes for multi-actor.
One canonical name per screen. Identical across diagram, narrative, per-flow list, and the index — and across amendments. Drift breaks enumeration.
Screens enumerable. The screens index is the complete union of every flow's screens/states (incl. loading + success), so wireframing can enumerate them all.
Irreversible actions are guarded. Every destructive/irreversible action carries a confirm or an undo.
Flow, not journey. The interaction graph only; emotion/channel/over-time is out.
Amend, don't regenerate. On a change, edit the affected flow in place + version the doc; never redraw untouched flows.
Capability boundary (when capability_record provided). Scope the document output to that record's boundary. Producing content outside the boundary (covering a refs entity as if it were owned; designing flows past an exit_point) is a scope violation — equivalent to inventing content that isn't in the spec.

Preferences (override-able):

One flow per goal/persona pairing; split a shared goal when personas diverge (state why).
Plain language in the narrative; expand abbreviations; label every diagram edge.
Proportion the document to the PRD's goal/persona set and the product's complexity — a thin utility fills few sections (no app shell, no resilience block); neither pad nor truncate. Fill Navigation & IA / resilience / accessibility where applicable.

Gotchas

Happy-path-only flows. Brittle — most real users leave the ideal path. The edge-case checklist (Step 5) + resilience (Step 6) exist so coverage is systematic.
Silent state-change. A step that mutates state and advances with no "what changed" feedback (Step 6) reads complete but leaves the user guessing.
Missing the loading/success state. A flow that leaps trigger→success hides the in-progress + confirmation screens wireframing must design (Step 5).
Diagram and narrative drift. Editing one and forgetting the other ships a contradiction. One artifact, two renderings; reconcile on every change.
Inventing product decisions inside a flow. Lift the assumption out (Step 10).
Screen names that drift across sections (or across an amendment). One stable name everywhere — the #1 amend regression.
AT-stranded error. An error state that is visually obvious but never announced leaves the screen-reader user stuck on a path the sighted user recovers from (Step 7).
Regenerating on a change. Re-drawing untouched flows on an amendment churns the doc and corrupts the cross-flow graph (Step 11).

Anti-patterns

"The diagram is enough." A flowchart alone isn't walkable in text; the numbered narrative + branch list is not optional.
"I'll bake the section list into the doc myself." Duplicates + drifts from the template. Always compose the structure from the template tool.
"Edge cases are an edge concern — happy path ships." Missing branches, unhandled states, and unguarded irreversible actions are the defects that strand users.
"The PRD didn't say, so I'll just decide." Silent product decisions belong in assumptions/open-questions.
"Layout while I'm here." Screen layout is a downstream document; this is the navigation graph only. Same for per-screen pixel a11y (wireframes/DS own it).
"Map the feelings per step." That is a user journey, not a user flow.
"Re-draw the whole doc for one new flow." Amend the delta, version the doc.

Production-grade quality bar

A user-flows document meets the bar when ALL hold (this is the same bar the review-side gate asserts; each scales with the product — a thin doc satisfying every applicable item passes):

Goal/persona coverage — no orphans. Every PRD goal/persona (framed as a job) maps to a flow; every flow traces back; standard flows grounded in their pattern.
Navigation & IA frame (where applicable). Entry-point taxonomy complete; the nav/app-shell model + wayfinding present for a multi-surface product; deep-linking + device divergence addressed where they apply; cross-flow hand-offs resolve.
Defined entry + exit. Every flow names all entry points (+ landing state) and a concrete success/confirmation state; alternate exits are clean.
Every decision branch resolved. Each decision lists all branches; each resolves.
Every error/edge state has a recovery — no dead ends. The checklist states (incl. loading + success) are present where applicable and route back; errors say what + how.
Interaction resilience (where applicable). Irreversible actions guarded; resume/ restart stated for multi-step flows; "what changed" feedback on state-changing steps; optimistic actions carry a revert.
Flow-level accessibility. Every path keyboard- and AT-completable; focus-order on step/route change; errors announced; no mouse-only step.
Flow quality (objective). No gratuitous step; irreversible actions prevented not only recovered; no cross-step recall burden; like jobs consistent.
Steps unambiguous + walkable. A reader follows the narrative without guessing; each step names its screen/state + the user action.
Both notations in sync. Flowchart AND narrative + branch/error list, same graph; swimlanes for multi-actor.
Screens enumerable for wireframing. The index is the complete union (incl. loading + success); one canonical name per screen; nothing orphaned.
Assumptions/open questions surfaced. Thin-PRD assumptions stated; no silent product decision; no journey content.
Amend-correct (on iteration). The change is scoped + edited in place; untouched flows unchanged; the doc is versioned + changelogged; breaking removals deprecated.

Output

A user-flows document in markdown: a per-doc version header + a coverage map (PRD goal/persona → flow), a Navigation & IA section, one section per flow (each a synced Mermaid flowchart + numbered narrative + branch/error list, with entry points, resilience & system-status, flow-level accessibility, screens/states incl. loading + success, and success criteria), a cross-flow transition list, a screens index, an assumptions/open-questions section, and a versioning/changelog section — composed onto the template tool's structure. Consumed by the review-side gate (which judges it against the bar above) and by downstream wireframing (which enumerates every screen the flows name). The method + bar are medium-independent: a future design-tool backend changes only the rendering, not the derivation or the bar.

Template provider (content-template-gateway capability) — supplies the user-flows section structure this skill composes onto; never duplicated here.
Research capability (deep-research, else web search) — grounds domain conventions + prior-art flow patterns and the derivation evidence.
Upstream input — the PRD (goals + personas the flows realize) and, where present, a design system (the nav/app-shell + components the flows reference). Never a blank page. On iteration, the existing user-flows doc is handed in.
reviewing-user-flows — the review-side gate that asserts the same bar; produce-side and review-side are single-sourced.
authoring-wireframes — the downstream consumer; each screen a flow names becomes a wireframe target, so a complete screens index is the handoff contract. Per-screen pixel accessibility is theirs, not this skill's.

Progressive disclosure

references/resilience-and-states.md — undo/confirm, resume/restart, system-status, optimistic-vs-confirmed, and the loading/success/state-matrix depth (Steps 5–6).
references/flow-accessibility.md — WCAG 2.2 SC 2.1.1 / 2.4.3 applied to flows; focus-order on route change; AT-completability; the flow-vs-pixel boundary (Step 7).
references/flow-quality.md — Nielsen's 10 heuristics mapped to flows; the objective subset; the no-false-revise boundary (Step 8).
references/amend-method.md — scope-the-ripple, edit-not-redraw, doc versioning + changelog, deprecation (Step 11).
references/sources.md — research provenance for the derivation method + the bar.

Body budget

description ≤ 1,024 chars (agentskills.io cap).
Body ~500 lines / 5,000 tokens (soft target — quality takes precedence; flag if consistently over 700 lines / 7,000 tokens) — kept in context every turn.
Per reference file: warn >10k tokens, error >25k.

About this skill