user-flow-mapping

name	user-flow-mapping
description	Maps complete user flows with entry points, decision nodes, happy paths, error paths, and exit points as numbered step sequences with branch conditions. Use when the user asks to map a user journey, document a workflow, plan navigation between screens, or diagram how users move through a product. Do NOT use for wireframing individual screens (use wireframe-specification), defining interaction animations (use prototype-spec), or business process mapping (use a business skill).
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"design planning analysis","category":"design-creative","subcategory":"ui-ux-design","depends":"","disclaimer":"none","difficulty":"intermediate"}

User Flow Mapping

When to Use

Use this skill when:

• The user asks to map a user flow, user journey, task flow, or "how users move through" a feature or product
• The user wants to document all navigation paths between screens (happy path, error paths, edge paths, abandon paths)
• The user needs to identify friction points, dead ends, or ambiguous branching in an existing product
• The user wants to plan a new feature's navigation before handing it to a designer or engineer
• The user is conducting a flow audit -- comparing current-state to proposed-state before a redesign
• The user needs to communicate product behavior across teams (engineering, QA, product, design) without ambiguity
• The user wants to identify what analytics events to instrument and where funnels break
• The user needs to document conditional access logic (authenticated vs. unauthenticated, free vs. paid tier, mobile vs. desktop)

Do NOT use when:

• The user wants to wireframe or spec the layout of a single screen (use wireframe-specification -- that skill handles component placement, spacing, and visual hierarchy)
• The user wants to define micro-interactions, gesture behaviors, or animation timing (use prototype-spec -- that skill handles state transitions and motion)
• The user wants to create a sitemap showing information architecture (a sitemap documents content hierarchy and URL structure, not user behavior sequences)
• The user wants to map a business process, organizational handoff, or back-office workflow with multiple departments (use a business-process-mapping skill -- those involve BPMN notation, swimlanes for business units, and SLA tracking, which are distinct concerns)
• The user wants to write a job story or user story (use a requirements skill -- stories are input artifacts; flows are output artifacts derived from stories)
• The user is asking about accessibility implementation details of a flow (use an accessibility-audit skill -- WCAG compliance on specific components is a different layer)
• The user wants to conduct usability testing or tree testing on an existing flow (use a usability-research skill)

---

Process

Step 1: Establish Flow Scope Before Writing Anything

Never begin mapping until you have answered six required questions. If the user hasn't provided them, ask explicitly:

• Goal (task-level): What is the single user task this flow accomplishes? Express it as a verb-noun pair: "purchase a product," "reset a password," "onboard as a new user," "submit an expense report." If the user gives a vague goal like "improve checkout," decompose it into discrete task-level flows first.
• Actor and persona state: Who is performing the task, and what do they know coming in? Distinguish between unauthenticated visitor, authenticated free-tier user, authenticated paid user, returning user, first-time user, admin, and guest. The actor's state determines which branches exist.
• Entry point(s): Where does the flow begin? Entry points are more numerous than users expect. For a checkout flow, entry points include: product detail page CTA, cart page, saved cart (email link), and social proof ad deep link. Each entry point may require a different first step.
• Success state: What is the binary completion condition? Frame it as a system-observable event: "order_confirmed event fires," "session token issued," "record created in database." Avoid vague success states like "user is happy."
• Constraints and dependencies: Authentication gates, external API calls (payment processors, identity verification, email delivery), platform constraints (mobile web vs. native app vs. desktop), feature flags, subscription tier gates, and regulatory requirements (age verification, GDPR consent).
• Out-of-scope adjacent flows: Explicitly list what this flow does NOT cover. If "forgot password" is a branch off the login flow, note it as a redirect exit to the "password reset" flow rather than mapping it inline.

If the user is documenting an existing product, ask them to describe the current flow verbally or share a screen inventory. Treat their description as raw input -- you will structure it, not transcribe it.

Step 2: Map the Happy Path as a Strict Linear Sequence

The happy path is the backbone. Every other path references it. Map it completely before adding any branches.

• Each step follows the atomic structure: [User action] → [System response] → [Resulting screen or state]. One action. One response. If you find yourself writing "user fills out the form and clicks submit," that is two steps: "user fills out form fields" and "user clicks submit button."
• Number steps as positive integers starting at 1. Reserve decimal suffixes (3a, 3b, 3e) strictly for branches.
• Write user actions in active voice, first-person perspective: "Taps 'Add to Cart' button," not "button is pressed."
• Write system responses in present tense: "Validates card number," "Displays loading spinner," "Creates session token."
• Include transitional system steps (loading states, background processing) as their own steps when they involve user-visible feedback or latency over 400ms. Users experience these steps even if they take no action during them.
• Assign a screen name to every step. The same screen always gets the same name. Build a screen inventory as you go -- if you use "Payment Screen" once, never later call it "Checkout Screen."
• The happy path ends at exactly one success exit step. If you think there are two success endpoints, you have two flows -- split them.
• Aim for 4--12 steps on the happy path. Flows shorter than 4 steps are usually sub-flows, not standalone flows. Flows longer than 12 steps are usually two flows stitched together -- identify the natural handoff point and split them.

Step 3: Identify and Catalogue All Decision Nodes

After completing the happy path, review each step against a decision node checklist:

• User-initiated decision: User must choose between two or more options (proceed vs. cancel, sign in vs. continue as guest, save vs. discard).
• System-evaluated condition: System checks a data condition (email exists in database, token valid and not expired, inventory in stock, card authorized, user is age-verified).
• Environment condition: Platform or context affects the path (mobile vs. desktop -- different screens; push notification entry -- skips landing screen; returning user -- pre-filled form).
• Permission gate: Feature requires a subscription, role, or explicit grant (free user hits a paid feature wall, unauthenticated user hits an auth gate, user without notification permission hits an OS prompt).

For each decision node, record: the step number it follows, the condition being evaluated, the party evaluating it (user or system), and the number of branches it creates. A two-option condition creates two branches. A three-option condition creates three branches (e.g., card authorized / card declined / card network error -- these are distinct outcomes with distinct recovery paths, not a single "failure" branch).

Label conditions precisely. "Email valid?" is imprecise -- it could mean format-valid or exists-in-database. Write "Email matches registered account?" instead. Precision here prevents ambiguous engineering requirements.

Step 4: Map Alternate Paths With Full Step Sequences

For each decision node, map every non-happy branch as a named alternate path. Use three path archetypes:

Alternate happy path: A valid route to the same success state that diverges from the primary happy path. Example: guest checkout vs. authenticated checkout. Both achieve "order confirmed." Map the guest checkout as a complete parallel sequence from its divergence point to the shared success exit. Do not shortcut with "similar to happy path but without login step" -- write every step explicitly.

Error path (recoverable): A condition that blocks forward progress but can be resolved. Specify:

• The trigger condition (what specifically went wrong)
• The exact error message or state the user sees (write real error copy, not "[error message]")
• The recovery action available to the user
• The step the flow returns to after recovery
• The maximum retry count if applicable (3 failed card attempts, 5 failed OTP attempts, etc.). After maximum retries, branch to an unrecoverable error exit.

Error path (unrecoverable): A condition that permanently terminates the flow. Examples: token expired with no renewal path, account suspended, required third-party service down. Specify:

• The trigger condition
• The exact error state the user sees
• Whether any partial data is preserved
• Any off-ramp for the user (contact support link, retry tomorrow messaging)

Abandon path: The user leaves the flow voluntarily. Classify abandon points:

• Explicit abandon: User clicks cancel, taps back, or closes a modal with an explicit dismiss action
• Implicit abandon: User navigates away, closes the browser, or lets a session time out
• For each abandon point, document whether partial state is preserved (cart persisted in localStorage, form fields saved as draft, session cookie retained)

Step 5: Map External Dependency Steps in Detail

Any step involving a third-party system or asynchronous operation requires expanded documentation:

• Identity the dependency: Payment processor, email delivery service, SMS gateway, identity verification provider, OAuth provider, or internal microservice with its own SLA.
• Document the three failure modes: (1) Timeout -- system never responds within expected window; (2) Error response -- system responds with a definitive failure; (3) Ambiguous response -- system response is unclear (network drop mid-transaction).
• Define expected latency: Payment authorization typically takes 1--3 seconds; email delivery 30 seconds to 5 minutes; SMS delivery 5--30 seconds; identity document verification 30 seconds to 3 minutes. These numbers belong in step annotations, not in vague "may take a moment" copy.
• Document the timeout threshold: What is the maximum wait before the UI shows an error? Common thresholds: API calls 10 seconds, payment processing 30 seconds, email verification polling 5 minutes. After timeout, the flow must have an explicit path -- not a dead end.
• Document the ambiguous-response path: If a payment gateway drops the connection after the charge but before the confirmation, what does the system show the user? This is among the most dangerous dead ends in product design. It must be explicitly addressed.

Step 6: Define and Label All Exit Points

Every path through the flow must terminate at exactly one of four exit types. No path may trail off without an exit label.

• Success exit: User achieved the goal. Specify: confirmation screen name, confirmation message, any side effects (email sent, record created, notification fired), and the next destination (where the user lands after success).
• Error exit (unrecoverable): Flow terminates due to a condition the user cannot resolve in-session. Specify: error screen name, error message, and available off-ramps (contact support, retry later, return to start).
• Abandon exit: User left the flow voluntarily or through inaction. Specify: whether state is preserved, for how long, and what the user experiences on return (resume prompt, fresh start, expired session).
• Redirect exit: Flow hands off to a sub-flow that, upon completion, returns control to this flow. Specify: the sub-flow name, the return step in the parent flow, and what state is passed between flows (user ID, cart contents, OAuth token).

Count your exits. A well-scoped flow of 6--10 steps typically has 1 success exit, 2--4 error exits, 1--2 abandon exits, and 0--2 redirect exits. A flow with 8 error exits is probably two flows or is over-specifying system error codes at the wrong abstraction level.

Step 7: Annotate for Engineering and Analytics

Add a metadata layer to the flow that makes it actionable for implementation:

Data requirements per step: What data must exist for the step to execute? "Step 4 requires: reset_token (UUID), token_created_at (timestamp), user_id (foreign key). Token expires when current_time minus token_created_at exceeds 3600 seconds." This level of specificity catches requirement gaps before engineering sprint planning.

Authentication and authorization per step: For each step, annotate whether it requires an active session, a specific role, or a specific token. Steps behind an auth gate must document the redirect behavior for unauthenticated access attempts.

Analytics instrumentation: For every funnel step -- any step the team will want conversion data on -- specify: event name (use snake_case), the event trigger (page load, button click, API response), and 2--3 key properties to capture (user_id, session_id, flow_variant, error_code). Common funnel steps to always instrument: flow entry, each major form submission, external dependency resolution, success exit, every error exit.

A/B test surfaces: Note steps where the team may want to run experiments (CTA copy, form field ordering, error message tone). Flag these as "experiment surface" without designing the experiment -- that is out of scope for a flow map.

Step 8: Compile and Structure the Final Specification

Assemble all components in the output format. Apply a final quality check:

• Every step on the happy path has a screen name
• Every decision node has a corresponding alternate path section
• Every alternate path has an exit point
• No step is a dead end (every step connects forward to another step or to an exit)
• Screen names are consistent throughout (build a screen glossary if the flow has more than 8 screens)
• Error messages are written in plain language (the spec is also a copywriting reference)
• Analytics events follow a consistent naming convention (snake_case, verb_noun or noun_verb pattern)
• External dependencies have latency annotations and failure paths

---

Output Format

## User Flow: [Flow Name]

### Overview
- **Goal:** [Verb-noun task statement, e.g., "Complete a first-time purchase as a guest user"]
- **Actor:** [Persona state, e.g., "Unauthenticated visitor with items in cart"]
- **Entry point(s):** [List all valid entry points with their origin screen]
- **Success state:** [System-observable event, e.g., "order_confirmed event fires; order record created"]
- **Out of scope:** [Adjacent flows explicitly excluded]
- **Key constraints:** [Auth gates, external dependencies, platform limits, regulatory requirements]

---

### Screen Inventory
| Screen Name          | Description                                      | Auth Required? |
|----------------------|--------------------------------------------------|----------------|
| [Screen Name]        | [What this screen is and does]                   | [Yes / No]     |

---

### Happy Path
| Step | User Action                        | System Response                          | Screen            | Data / Notes                          |
|------|------------------------------------|------------------------------------------|-------------------|---------------------------------------|
| 1    | [Specific user action]             | [Specific system response]               | [Screen Name]     | [Latency / data required / notes]     |
| 2    | [Specific user action]             | [Specific system response]               | [Screen Name]     |                                       |
| ...  | ...                                | ...                                      | ...               |                                       |
| N    | [Final action]                     | [Success confirmation response]          | [Screen Name]     | **SUCCESS EXIT**                      |

---

### Decision Nodes
| After Step | Condition                              | Evaluator | Branch A (happy)              | Branch B                      | Branch C (if applicable)      |
|------------|----------------------------------------|-----------|-------------------------------|-------------------------------|-------------------------------|
| [Step #]   | [Precise condition statement]          | System    | [Continue to step N]          | [Go to path name, step Xe]    |                               |
| [Step #]   | [Precise condition statement]          | User      | [Continue / path name]        | [Alternate path name]         |                               |

---

### Alternate Paths

#### [Path Name -- e.g., "Guest Checkout Path"]
*Diverges from happy path after step [N]. Converges at step [N] / shares success exit.*

| Step  | User Action                        | System Response                          | Screen            | Notes                                 |
|-------|------------------------------------|------------------------------------------|-------------------|---------------------------------------|
| [N]a  | [Specific action]                  | [Specific response]                      | [Screen Name]     |                                       |

---

#### [Path Name -- e.g., "Card Declined -- Recoverable"]
*Triggered at step [N]. Recoverable: returns to step [N] after user action. Max [X] retries.*

| Step  | Trigger Condition                  | Error State Shown to User                | Screen            | Recovery Action               |
|-------|------------------------------------|------------------------------------------|-------------------|-------------------------------|
| [N]e  | [Exact trigger, e.g., "Issuer returns decline code 05"] | "[Exact error message copy]" | [Screen Name] | [Return to step N / Exit] |

---

#### [Path Name -- e.g., "Session Timeout -- Unrecoverable"]
*Triggered at step [N]. Unrecoverable: flow terminates.*

| Step  | Trigger Condition                  | Error State Shown to User                | Screen            | Off-Ramp Available            |
|-------|------------------------------------|------------------------------------------|-------------------|-------------------------------|
| [N]e  | [Exact trigger]                    | "[Exact error message copy]"             | [Screen Name]     | [Contact support / retry / return to start] |

---

### External Dependencies
| Step | Dependency                  | Expected Latency    | Timeout Threshold | Timeout Behavior                     | Ambiguous-Response Behavior           |
|------|-----------------------------|---------------------|-------------------|--------------------------------------|---------------------------------------|
| [#]  | [Service name / type]       | [X--Y seconds]      | [Z seconds]       | [Show error X, branch to path Y]     | [Show "processing" state, confirm via polling] |

---

### Exit Points
| Type       | After Step | Condition                         | User Sees                            | State Preserved?        | Next Destination             |
|------------|------------|-----------------------------------|--------------------------------------|-------------------------|------------------------------|
| Success    | [Step #]   | [System-observable completion]    | [Screen name + confirmation copy]    | N/A                     | [Where user lands next]      |
| Error      | [Step #]   | [Unrecoverable failure condition] | [Error screen name + message]        | [Yes / No / Partial]    | [Off-ramp link or dead end]  |
| Abandon    | [Step #]   | [User-initiated exit]             | [Save prompt / nothing]              | [Yes, 30 days / No]     | [Resume URL / fresh start]   |
| Redirect   | [Step #]   | [Sub-flow handoff condition]      | [Sub-flow start]                     | [State passed: list]    | [Returns to step N]          |

---

### Analytics Events
| Step | Event Name                  | Trigger                          | Key Properties                                      | Purpose                              |
|------|-----------------------------|----------------------------------|-----------------------------------------------------|--------------------------------------|
| [#]  | [snake_case_event_name]     | [Page load / click / API response] | user_id, session_id, [domain-specific property]   | [What funnel question this answers]  |

---

### Open Questions
| # | Question                                    | Owner          | Blocks             |
|---|---------------------------------------------|----------------|--------------------|
| 1 | [Unresolved requirement or ambiguity]       | [Product / Eng / Design] | [Step # or path name] |

---

Rules

1. Map the happy path first, completely, before writing a single branch. Every branch references step numbers from the happy path. If you write branches before the happy path is complete, your step numbers will shift and your cross-references will break.

2. Each step is exactly one user action paired with exactly one system response. "User fills out the registration form" is not a step -- it is 4--6 steps. Atomic steps allow QA to write test cases from the flow map without ambiguity. If you cannot write a single automated test assertion for a "system response," the step is not atomic.

3. Never write a vague error message. Write the exact message the user will see: "Your session has expired. Please log in again." not "[Session expiry message]." The flow map is the canonical source for error copy before a content designer reviews it. Placeholder copy propagates into shipped products.

4. Every decision node must document the evaluator -- user or system. A user choice (proceed vs. cancel) and a system condition check (token valid?) both create branches, but they have completely different implementation implications. Mislabeling the evaluator causes engineering to build the wrong thing.

5. External dependency steps must have three explicitly documented failure modes: timeout, definitive failure response, and ambiguous/indeterminate response. The ambiguous response case (network drop mid-transaction, payment charged but confirmation lost) is the most dangerous dead end in product flows. It must never be omitted.

6. Looping paths (retry flows) must specify a maximum iteration count. "Returns to step 4" with no maximum creates an infinite loop in the spec. Specify the limit and the escalation path: "Returns to step 4, max 3 attempts; on third failure, branches to account-locked error exit."

7. Screen names are controlled vocabulary. Establish the screen inventory in Step 1 of your process and never deviate from it. If the same screen appears under two names, engineers may build two screens. A screen name change mid-document is a defect in the spec, not a stylistic choice.

8. Redirect exits must document both the outbound state (what is passed to the sub-flow) and the return point (which step in the parent flow execution resumes from). A redirect that says only "goes to create account flow" is incomplete. Specify: "Redirect to Create Account flow, passing cart_id and session_id. On Create Account success, return to step 4 of this flow with authenticated user session established."

9. If a flow has more than 12 happy-path steps, decompose it. Flows of 15--20 steps are almost always two flows with a redirect exit between them. Identify the natural midpoint (usually a major state change: account created, payment authorized, identity verified) and split. A parent flow with redirect exits to sub-flows is always cleaner than a single mega-flow.

---

Edge Cases

Multi-actor flows (marketplace checkout with buyer and seller, or two-sided approval workflows): Create a swimlane section beneath the happy path table with one labeled lane per actor. Steps that involve only one actor appear in that actor's lane. Steps at the boundary -- where one actor's action triggers a system notification to the other, or where both actors must complete an action before the flow proceeds -- are annotated as "handoff steps." Document what the waiting actor sees during the other actor's action (a pending state screen, an email notification, nothing). Do not fold multi-actor flows into a single-actor flow by treating one actor as a "system response" -- that obscures real UX decisions about the secondary actor's experience.

Flow re-entry after an async break (email verification, document review, delayed approval): Some flows have a natural pause of minutes, hours, or days while an async process completes. Treat the pause as two sub-flows: the submission sub-flow (user submits and sees a confirmation screen) and the re-entry sub-flow (user returns via email link or push notification and continues). Document both. The re-entry sub-flow has its own entry point (email link or notification), its own authentication check (is the token in the link still valid?), and its own "resume" step that continues the parent flow. Specify: what does the user see if they return before the async process completes? What if they return after it has timed out?

Feature-flagged or A/B-tested steps: When a step has two variants under test, document both variants as named alternate paths -- not as a single step with a parenthetical note. Use labels like "Variant A (control): Single-page checkout" and "Variant B: Step-by-step checkout wizard." Specify the experiment surface annotation and what the branching condition is (user is in experiment cohort A or B). This ensures QA can test both variants and analytics can segment by variant.

Accessibility-forced alternate paths: Some users will interact with the flow via keyboard navigation, screen reader, or voice input, producing interaction sequences that differ from mouse/touch flows. For flows with complex interactions (drag-and-drop, multi-step modals, file uploads), note steps where the interaction model changes for assistive technology users. Example: "Step 3 -- file upload: mouse users drag and drop; keyboard/screen reader users interact with a file picker dialog triggered by a visibly labeled button." Flag these for accessible design review without specifying WCAG implementation details (that belongs in an accessibility audit).

Flow audit of an existing, potentially broken product: If the user is documenting a current-state flow to identify problems, produce two artifacts: a "Current State" flow map that faithfully documents the existing behavior (including its broken paths, dead ends, and missing error handling), followed by a "Friction Annotations" table that lists every identified problem with its step reference, problem type (dead end, missing error message, unnecessary decision node, excessive steps, inconsistent naming), severity (blocking / high / medium / low), and proposed resolution. Then produce a "Proposed State" flow map. The separation of current-state and proposed-state is critical -- conflating them produces a spec that no one can implement because it is unclear which parts already exist.

Mobile-specific flow variations: Mobile flows often diverge from desktop flows due to platform capabilities (biometric authentication replaces password entry, camera-based document capture replaces file upload, push notification entry bypasses the web entry point entirely). When the user specifies a mobile-native context, add a "Platform Variants" section to each step where mobile behavior differs from desktop. Document specifically: what is different (biometric prompt vs. password field), which platform each variant applies to (iOS / Android / mobile web), and whether the variant produces a different step count or just a different interaction on the same step. A mobile-native flow that simply copies a desktop flow without accounting for platform capabilities is not a mobile flow -- it is a desktop flow with a smaller screen.

Regulatory and consent gates (GDPR, CCPA, age verification, financial compliance): Consent and legal gates appear as mandatory decision nodes that the team may want to minimize but cannot remove. Document these as first-class decision nodes with their legal requirement noted (e.g., "GDPR Article 6(1)(a) -- explicit consent for marketing emails required before account creation completion"). The branches are: user consents (continue), user declines (continue with restricted permissions, not block -- most consent is optional for account creation), user does not act (do not proceed without explicit action). Document the minimum required consent disclosures as step annotations. Flag ambiguous consent UX patterns (pre-checked checkboxes, bundled consent) as design risks in the Open Questions table.

---

Example

Input: "Map the user flow for adding a payment method to an account in a SaaS web app. The user is already logged in. They can add a credit card or a bank account via ACH."

Output:

---

User Flow: Add Payment Method

Overview

• Goal: Add a verified payment method to an existing account for future billing
• Actor: Authenticated user with an active account, no payment method on file (or adding an additional method)
• Entry point(s): (1) Billing Settings page "Add Payment Method" button; (2) In-context prompt during upgrade flow when no payment method exists
• Success state: payment_method_added event fires; payment method record created and marked as verified in billing system; method appears in Billing Settings payment methods list
• Out of scope: Removing an existing payment method, setting a default payment method, processing a charge against the new method
• Key constraints: User must be authenticated with an active session. Credit card tokenization handled by third-party payment processor (PCI DSS compliance -- raw card data never touches application server). ACH verification requires micro-deposit confirmation, which takes 1--2 business days and requires a second user session to complete.

---

Screen Inventory

Screen Name	Description	Auth Required?
Billing Settings	Lists current payment methods, billing history, plan details	Yes
Add Payment Method Modal	Entry point modal with method-type selector (card vs. ACH)	Yes
Card Entry Form	Tokenized card input fields (number, expiry, CVV, billing ZIP)	Yes
ACH Bank Entry Form	Bank routing number and account number entry	Yes
ACH Verification Pending	Confirmation screen showing micro-deposit pending status	Yes
ACH Verify Deposits	Form for entering two micro-deposit amounts to verify account	Yes
Payment Method Success	Inline success confirmation within Billing Settings	Yes
Payment Method Error	Inline error state within the active form	Yes

---

Happy Path (Credit Card)

Step	User Action	System Response	Screen	Data / Notes
1	Clicks "Add Payment Method" button	Opens Add Payment Method Modal	Billing Settings	Modal overlays Billing Settings
2	Selects "Credit or Debit Card" option	Highlights card option; activates "Continue" button	Add Payment Method Modal	Default selection; ACH is the alternate path
3	Clicks "Continue"	Renders Card Entry Form with tokenized input fields	Card Entry Form	Payment processor iframe loaded; no card data touches app server (PCI)
4	Enters card number, expiry, CVV, and billing ZIP	Inline format validation as user types; no submission yet	Card Entry Form	Luhn algorithm validates card number format client-side
5	Clicks "Add Card"	Submits tokenized card data to payment processor; shows loading spinner	Card Entry Form	Latency: 1--3 seconds; timeout threshold: 10 seconds
6	(System step -- no user action)	Payment processor returns card token and card fingerprint	Card Entry Form	Token stored; raw card data discarded
7	(System step -- no user action)	App server creates payment method record; sets as default if first card	Payment Method Success	payment_method_added event fires; SUCCESS EXIT
8	Views success state	Billing Settings reloads with new card in payment methods list	Billing Settings	Success toast: "Visa ending in 4242 added successfully."

---

Decision Nodes

After Step	Condition	Evaluator	Branch A (happy)	Branch B	Branch C
2	Which payment method type does user select?	User	Credit/Debit Card -- continue to step 3	ACH Bank Account -- go to ACH Path, step 2a
4	Are all required card fields populated and format-valid?	System	Continue to step 5	Inline validation errors shown -- stay at step 4
5--6	Does payment processor return a valid card token?	System	Continue to step 7 (token received)	Card tokenization error -- go to path "Card Tokenization Failure"	Timeout (10s) -- go to path "Processor Timeout"
6	Does card pass basic verification (Luhn + BIN check)?	System	Continue to step 7	Card rejected at tokenization -- go to path "Card Rejected at Entry"

---

Alternate Paths

ACH Bank Account Path

Diverges from happy path at step 2. ACH verification requires micro-deposit confirmation in a second session (1--2 business days later). This path has two phases: initial submission and deposit verification.

Phase 1 -- Bank Account Submission:

Step	User Action	System Response	Screen	Notes
2a	Selects "Bank Account (ACH)" option	Highlights ACH option; activates "Continue"	Add Payment Method Modal
3a	Clicks "Continue"	Renders ACH Bank Entry Form	ACH Bank Entry Form
4a	Enters routing number and account number	Validates routing number format (9 digits, ABA checksum)	ACH Bank Entry Form	ABA checksum validates routing number format
5a	Clicks "Add Bank Account"	Submits to ACH processor; initiates micro-deposit request	ACH Bank Entry Form	Latency: 2--4 seconds; micro-deposits sent in 1--2 business days
6a	(System step)	App creates unverified payment method record; sends confirmation email	ACH Verification Pending	Email: "Bank account added -- verify deposits to activate"
7a	Views pending confirmation screen	Displays pending status with instructions	ACH Verification Pending	PHASE 1 SUCCESS -- flow pauses for async verification

Phase 2 -- Micro-Deposit Verification (separate session, 1--2 business days later):

Step	User Action	System Response	Screen	Notes
8a	Returns to Billing Settings; clicks "Verify" on pending bank account	Renders ACH Verify Deposits form	ACH Verify Deposits	Entry point: Billing Settings or email link
9a	Enters two micro-deposit amounts (in cents)	Validates amounts against stored expected values	ACH Verify Deposits	Max 3 attempts before account verification locked
10a	Clicks "Verify"	Amounts match -- updates payment method status to verified	Billing Settings	payment_method_verified fires; SUCCESS EXIT

---

Card Field Validation Errors (Recoverable)

Triggered at step 4. User remains on Card Entry Form until all fields are valid.

Step	Trigger Condition	Error State Shown to User	Screen	Recovery Action
4e	Card number fails Luhn algorithm	"Please enter a valid card number."	Card Entry Form	User corrects field; retry
4e	Expiry date is in the past	"This card has expired. Please use a different card."	Card Entry Form	User corrects field; retry
4e	CVV is wrong digit count for card type	"Please enter a valid security code."	Card Entry Form	User corrects field; retry
4e	Billing ZIP is not 5 digits (US) or valid postal format	"Please enter a valid billing ZIP code."	Card Entry Form	User corrects field; retry

---

Card Rejected at Tokenization (Recoverable)

Triggered at step 6 when the payment processor rejects the card during token generation. Max 3 attempts per session.

Step	Trigger Condition	Error State Shown to User	Screen	Recovery Action
6e	Processor returns: card number invalid (BIN not found)	"We couldn't verify this card. Please check your card details and try again."	Card Entry Form	Return to step 4; max 3 attempts
6e	Processor returns: card type not accepted	"We don't accept this card type. Please use Visa, Mastercard, or American Express."	Card Entry Form	Return to step 4; switch card
6e	3 consecutive tokenization rejections	"We're having trouble adding your card. Please contact support or try a different payment method."	Payment Method Error	ERROR EXIT -- link to support

---

Processor Timeout (Unrecoverable in session -- retry available)

Triggered at step 5 when the payment processor does not respond within 10 seconds.

Step	Trigger Condition	Error State Shown to User	Screen	Off-Ramp
5e	No response from processor after 10 seconds	"Something went wrong connecting to our payment service. Please wait a moment and try again."	Payment Method Error	"Try again" button returns to step 3
5e	Timeout on retry attempt	"We're still having trouble. This may be a temporary issue. Please try again in a few minutes."	Payment Method Error	"Done" returns to Billing Settings

---

ACH Micro-Deposit Amount Mismatch (Recoverable -- max 3 attempts)

Triggered at step 9a when the entered amounts do not match the stored micro-deposit values.

Step	Trigger Condition	Error State Shown to User	Screen	Recovery Action
9ae	One or both amounts do not match	"Those amounts don't match our records. Please double-check and try again. You have [X] attempts remaining."	ACH Verify Deposits	Return to step 9a; max 3 total attempts
9ae	3 failed verification attempts	"This bank account could not be verified and has been removed. Please add it again or use a different payment method."	Billing Settings	ERROR EXIT -- bank account record deleted; ach_verification_failed event fires

---

External Dependencies

Step	Dependency	Expected Latency	Timeout Threshold	Timeout Behavior	Ambiguous-Response Behavior
5--6	Payment processor (card tokenization)	1--3 seconds	10 seconds	Show processor timeout error; offer retry to step 3	Log ambiguous response; do not create payment method record; show generic retry error
5a--6a	ACH processor (micro-deposit initiation)	2--4 seconds	15 seconds	Show timeout error; do not create unverified record; offer retry	Log event; check ACH processor dashboard; do not create duplicate record

---

Exit Points

Type	After Step	Condition	User Sees	State Preserved?	Next Destination
Success	7--8	Card token received; payment method record created	Billing Settings with "Visa ending in 4242 added" success toast	N/A	Billing Settings
Success	10a	ACH micro-deposits verified; method status updated	Billing Settings with "Bank account verified and active" toast	N/A	Billing Settings
Pending	7a	ACH submitted; awaiting micro-deposit completion	ACH Verification Pending screen; confirmation email sent	Unverified record held for 7 days	Returns via Billing Settings
Error	6e (3rd)	3 consecutive card tokenization failures	Payment Method Error screen with support link	No	Support page or Billing Settings
Error	5e (retry)	Processor timeout on retry	Payment Method Error with "try later" message	No	Billing Settings
Error	9ae (3rd)	3 failed ACH verification attempts	Billing Settings with error message; unverified record deleted	No	Billing Settings
Abandon	Any	User closes modal or navigates away	Nothing (modal closes or navigation proceeds)	No partial state saved	Previous page or Billing Settings

---

Analytics Events

Step	Event Name	Trigger	Key Properties	Purpose
1	payment_method_flow_started	Modal opens	user_id, account_id, entry_point (settings / upgrade_prompt)	Track flow initiation rate by entry point
2	payment_method_type_selected	User selects type	user_id, method_type (card / ach)	Track card vs. ACH preference
5	card_submission_attempted	"Add Card" clicked	user_id, card_brand (if detectable from BIN)	Track submission attempt rate
7	payment_method_added	Record created	user_id, method_type, card_brand, is_first_method (bool)	Primary success metric for this flow
5a	ach_submission_attempted	"Add Bank" clicked	user_id	Track ACH initiation rate
6a	ach_pending_created	Unverified record created	user_id	Track ACH funnel entry
10a	payment_method_verified	ACH verification completes	user_id, days_to_verify	Track ACH full-funnel completion and time-to-verify
6e	card_tokenization_failed	Processor rejection	user_id, error_code, attempt_number	Track card rejection rate by error code
9ae	ach_verification_failed	3rd failed attempt	user_id	Track ACH drop-off at verification step
5e	payment_processor_timeout	10s timeout fires	user_id, method_type, attempt_number	Monitor processor reliability and timeout frequency

---

Open Questions

#	Question	Owner	Blocks
1	Should the app attempt instant ACH verification via bank OAuth (e.g., Plaid Link) before falling back to micro-deposits? Instant verification eliminates the 1--2 day delay for supported banks.	Product	ACH Path design
2	What is the business rule when a user has 3 failed tokenization attempts? Lock the user from adding cards for 24 hours, or just surface a support contact?	Product	Card error exit handling
3	For users entering from the upgrade flow, should a successful card add automatically complete the upgrade, or should the user confirm separately? This affects whether there is a redirect exit back to the upgrade flow.	Product	Exit points, redirect exit spec
4	Is billing ZIP required for all geographies or only US cards? International users may not have a ZIP equivalent.	Engineering	Step 4 validation rules