design-flow

name	design-flow
description	Design a new user flow before building it, or audit an existing flow for friction, using the product-flow-designer agent. Use when: planning a new multi-step feature (onboarding, signup, booking, invite, wishlist) before implementation, or auditing a conversion journey for drop-off, dead-ends, or mobile friction. Invoke with: /design-flow <flow> [design|evaluate]

Design Flow

Run a focused user-flow session with the product-flow-designer agent, then hand the result to the right next step. One agent, two modes — DESIGN (a journey that doesn't exist yet) and EVALUATE (an existing journey).

Type: Rigid workflow, single-agent. Follow steps exactly. The whole point is to drive the specialized agent and wire its output downstream — do NOT hand-roll a flow yourself in its place (see Rules).

This is a journey-level UX tool. It is not a per-PR review (that's review-design) and not a functional QA pass (that's test-drive, which asks "does it work" — this asks "is it low-friction").

---

Step 1: Resolve Flow and Mode

Parse <flow> and the optional mode from the invocation.

• Mode given (design | evaluate): use it.
• Mode omitted: infer — grep lib/klass_hero_web/router.ex for the flow. Has a route → default evaluate (it exists). No route → default design (it's new). If the request is "redesign the existing X" or otherwise ambiguous, confirm with the user before proceeding.

High-value journeys worth auditing (suggest these when the user is vague about which flow): booking/enrollment, registration→activation, provider onboarding, staff invite/claim.

Then branch to Step 2A (design) or Step 2B (evaluate).

Step 2A: DESIGN (upstream — before code exists)

No server needed; this mode is generative.

Spawn one product-flow-designer subagent in DESIGN mode:

Design the "<flow>" user flow. It does not exist yet.

Mode: DESIGN. Anchor to the nearest existing klass-hero flow + pattern — REQUIRED: name a real
route/module, don't hand-wave it. Use the real personas. Label every step (proposed). Produce the
journey flow map, anticipated friction, edge cases, and success metrics — NOT an implementation/DDD design.

Keep the output at journey granularity (screens, steps, decisions, friction) — bounded contexts, ports, and Ecto belong to the plan, not here.

Handoff (do not skip):

• If the intent is still fuzzy, recommend superpowers:brainstorming first.
• Then hand the flow map into superpowers:writing-plans as the starting point for the implementation plan. Do not write code from this skill.

Step 2B: EVALUATE (audit an existing journey)

Server preflight (required). The agent must walk the journey — a code read is not an audit. Probe http://localhost:4000 and one real route (e.g. the flow's entry route): the server must be healthy (2xx/3xx), not merely listening. A stale process returning 5xx counts as down.

• Healthy: proceed.
• Down or 5xx: ask the user to (re)start it (mix phx.server). If they decline, STOP — do not let the agent audit from code alone (it would miss the rendered/mobile dead-ends, which is exactly what RED testing showed a code-only pass misses).

Resolve dynamic route params first. If the entry route has a dynamic segment (e.g. /programs/:id/booking), resolve :id to a real seeded record before walking — navigate in from the listing page, or query a valid id (Tidewave / a quick SQL select). Walking a bogus id audits the redirect, not the actual screen. Pass the resolved URL to the agent.

Spawn one product-flow-designer subagent in EVALUATE mode:

Evaluate the "<flow>" flow for friction.

Mode: EVALUATE. Entry route: <resolved URL, real ids>. Role: <parent|provider|admin> (log in with the seed user).
Server: http://localhost:4000 (confirmed healthy). Read router + LiveViews to map it, then WALK it
at 375 and 1280, screenshotting each step and every branch (error/empty/validation/role wall).
Produce the flow map with counts (steps/fields/decisions/taps), quantified friction, and severity.

Handoff (do not skip): after presenting the report, offer to file each Blocker / Major finding as a GitHub issue via /create-issue "<finding>" — one invocation per finding. Let create-issue validate against code, dedup, classify, and pick labels (it selects design for UX issues; the repo has no frontend label). Never auto-file without the user's confirmation.

---

Rules

• Single agent, no fan-out. Spawn exactly one product-flow-designer. This is not review-design — do not parallel-spawn or consolidate multiple agents.
• Always spawn the agent. Do NOT substitute your own hand-sketched flow or audit. The failure this skill prevents is improvising a manual pass and skipping the specialized agent (and, for evaluate, skipping the live walk).
• Mode discipline. DESIGN = generative, every step (proposed), journey-level (no DDD/Ecto). EVALUATE = grounded in router+LiveViews and walked in the browser. Never blur them.
• Server-healthy gate for evaluate. Healthy response required; 5xx = down; STOP rather than audit from code only.
• Honour the handoffs. DESIGN → writing-plans (after optional brainstorming). EVALUATE → offer per-finding /create-issue for Blocker/Major. The skill's job is routing + handoff, not redoing the agent's work or writing code.
• Not functional QA. test-drive covers "does it work"; this covers "is it low-friction." Don't duplicate it.