map-user-flow

name	map-user-flow
description	Maps multi-step in-product flows — screens, decisions, transitions, platform-native touchpoints (dock, menu bar, widgets, notifications, Live Activity), edge cases, and error states for a feature or user journey. Use when designing or auditing a feature spanning multiple screens, states, or platforms. Not for visual brand design (use create-brand), landing-page architecture (use brief-landing-page), or technical architecture (use architect-system).
argument-hint	[feature or flow to map]
allowed-tools	Read Grep Glob Bash
metadata	{"version":"1.0.0","budget":"standard","estimated-cost":"$0.20-0.50"}

User Flow Design — Orchestrator

Design Step 2 of 2. Maps navigation paths, decisions, edge cases, platform-native touchpoints, and screen transitions into a validated flow (Mermaid + ASCII wireframes + per-surface mini-frames).

Core Question: "Can the user complete their goal without thinking — on every surface of every platform it ships on?"

Why, methodology, principles, history: references/playbook.md [PLAYBOOK].

When To Use

Design / redesign / audit a feature with multiple screens / decisions / states / platforms, or map a new platform-native surface (widget, Live Activity, watch app) into an existing flow.

Not for: brand (/create-brand) · API (/architect-system) · decomposition (/breakdown-tasks) · scoping (/discover) · single-page landing (/brief-landing-page).

Critical Gates — Read First

Gate 1 (platforms+surfaces) fires before Pre-Dispatch — wireframe size, entry triggers, per-surface edge states all depend on it.

1. No Layer 1 before platforms + surfaces enumerated (references/platform-touchpoints.md).
2. Reject "cross-platform". Enumerate explicitly from the 13-platform list.
3. No diagrams before structure.
4. No skipping edge cases. Error / empty / loading / permission / offline + per-surface edge states.
5. Challenge >7 happy-path steps (Miller).
6. One flow = one file.
7. Stale product context (>30 days) → re-run research-icp.

Full rationale + 13-platform list + critic-FAIL handling: references/procedures/gates-and-rubric.md [PROCEDURE].

Quality Gate

Critic (agents/critic-agent.md) runs the full rubric. Non-negotiable PASS:

• Platforms + surfaces enumerated; every platform × surface has entry + mini-frame + per-surface edge state (dimensions match references/platform-touchpoints.md)
• Every decision point ≥2 labeled exits; no dead-end errors
• Happy path ≤7 steps; ≤3 primary actions per screen
• Every core screen: ASCII wireframe + 2-4 sentence Description; CTAs match structure actions
• 2-3 critical edge-state variants included

Before Starting

Apply references/_shared/before-starting-check.md [PLAYBOOK]. budget: standard; --fast forces Single-Agent Fallback per references/_shared/mode-resolver.md [PROCEDURE]. Safety gates supersede --fast. Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md.

Artifact	Source	Required?
research/product-context.md	research-icp	Recommended (>30d → re-run)
docs/forsvn/experience/{audience,technical,goals}.md	any	Recommended
implementation-roadmap/canonical-paths.md	architect-system	Optional
brand/{DESIGN,BRAND}.md	create-brand	Optional

Pre-Dispatch

Dimensions: feature, role/persona, goal, platforms (explicit), surfaces per platform, primary surface, constraints (auth + min OS). Read order + Warm/Cold Start prompts (with platforms+surfaces gate) + write-back + brief-context contract: references/procedures/pre-dispatch.md · references/pre-dispatch-prompts.md [PROCEDURE].

Artifact Contract

• Path: docs/forsvn/artifacts/product-map-user-flow-<YYYY-MM-DD>-<flow-name>.md (flat v2; one file per flow; index auto-generated at ≥2 slugs). Lifecycle: pipeline.
• Frontmatter: skill, version, date, status, stack: product, review_surface: html (FIRE preview while decision_state: pending), decision_state, flow_name, platforms, plus manifest-sync lifecycle, produced_by, provenance. v2 schema: references/_shared/artifact-contract-template.md.
• Required sections + per-flow template + index.md + filename + version-increment: references/report-template.md [PROCEDURE].
• Consumed by: architect-system, breakdown-tasks, forsvn, review-work.

Tooling

Upstream tool-redirect.md.

Routing + Dispatch

Single route, full stack. Flows >15 screens auto-split via structure-agent sub-flow decomposition. Pipeline: Step 0 → L1 ∥ (structure ∥ edge-case) → Merge → L2a ∥ (diagram ∥ wireframe) → L2b seq (validation → critic). Critic FAIL re-dispatches (max 2 cycles).

Agent manifest, spawn mechanics, dispatch tables, Single-Agent Fallback: references/procedures/dispatch-mechanics.md · references/dispatch-protocol.md. Worked example: references/examples/checkout-walkthrough.md [EXAMPLE].

Anti-Patterns

13-pattern catalog (happy-path-only edge cases, generic screen names, wireframe drift, "cross-platform" creep) + when-to-defer + critic-FAIL: references/anti-patterns.md [ANTI-PATTERN].

Chain Position

Prev: create-brand (optional). Next: architect-system → breakdown-tasks. Defer to: discover, create-brand, breakdown-tasks. Re-run on: feature changes, new research, usability failures.

Durable Rules (protected)

Completion Status

• DONE — flow specified for all declared platforms with structure, wireframes, edge states, per-surface coverage; critic PASS.
• DONE_WITH_CONCERNS — flow complete but surfaces under-specified (e.g., widget refresh budget unverified, Live Activity ceiling not modeled); flagged inline.
• BLOCKED — feature scope unclear or contradictory across platforms.
• NEEDS_CONTEXT — research/product-context.md missing; recommend research-icp.