AI-Ready Docs

04 / UFD

User Flow Document

How does the user move through the product?

The User Flow Document describes how users move through the product to complete tasks. It maps actions, decisions, system responses, alternate paths, and outcomes without defining the visual design of the interface.

Layer
Product
Primary purpose
Define how users move through the product to complete tasks.
Used by
Product / Design / Engineering / AI
On this page
  1. 01What is it?
  2. 02Why do we need it?
  3. 03When do we create it?
  4. 04Who benefits from it?
  5. 05What does it contain?
  6. 06What does it NOT contain?
  7. 07What does a user flow look like?
  8. 08How does AI use it?
  9. 09How does it connect to other documents?
  10. 10Example
  11. 11Template
  12. 12Common mistakes
01

What is it?

The User Flow Document maps how a user moves through a product to complete a task. It describes the sequence of actions, decisions, system responses, alternate paths, and outcomes involved in that journey.

  • FSD

    What

  • BRD

    Rules

  • UFD

    Behavior

  • DSD

    Experience

02

Why do we need it?

A feature description tells us what capability exists. A business rule tells us what conditions govern it. A user flow connects those decisions into a sequence of behavior.

Without a user flow

Feature
Screens
Assumptions about sequence
Inconsistent behavior

With a user flow

Feature
User action
System response
Decision
Next action
Outcome
03

When do we create it?

The UFD is created once the product functionality and important business rules are understood well enough to map the user's journey.

This is an information relationship, not a rigid waterfall. User flows can expose new scenarios that require clarification in the rules or feature scope.

PRD
FSD
BRD
UFD
DSD / Engineering
Implementation
04

Who benefits from it?

  • Product

    Uses it to understand how a feature is experienced as a complete task.

  • Design

    Uses it to design the screens, states, transitions, and interactions needed to support the journey.

  • Engineering

    Uses it to understand the expected sequence of actions, responses, and states.

  • AI agent

    Uses it to understand the behavioral sequence that the implementation needs to support.

05

What does it contain?

These are the fields a user flow can define.

  1. 01

    Flow ID

    A unique identifier for the user flow.

  2. 02

    Flow Name

    A concise name describing the journey.

  3. 03

    Goal

    What the user is trying to accomplish.

  4. 04

    Actor

    The user or role performing the journey.

  5. 05

    Entry Point

    Where the journey begins.

  6. 06

    Preconditions

    What must already be true before the journey begins.

  7. 07

    User Actions

    The actions the user performs.

  8. 08

    System Responses

    How the system responds to those actions.

  9. 09

    Decision Points

    Places where the journey can branch based on a condition or decision.

  10. 10

    Alternate Paths

    Valid paths other than the primary journey.

  11. 11

    Error / Empty / Exceptional States

    Relevant non-happy-path states that affect the journey.

  12. 12

    End State

    How the journey concludes.

  13. 13

    Dependencies

    Other features, rules, permissions, or conditions that affect the journey.

This section defines the sequence and behavior of the journey — not its visual design.

06

What does it NOT contain?

  • Product vision
  • Feature inventory
  • Detailed business rules
  • Visual design
  • Typography or colors
  • Component specifications
  • Database schema
  • API contracts
  • Technical architecture
  • Implementation code

FSD

What capability exists?

BRD

What rules govern it?

UFD

How does the user move through it?

DSD

How is that journey experienced?

DDD / ASD / TAD

How is it technically implemented?

07

What does a user flow look like?

Flow

Flow ID
FLOW-001
Flow name
Create Project
Goal
Create a new project.
Actor
Authenticated user
Entry point
Projects
Preconditions
User is authenticated.

Primary flow

01

User selects Create Project.

02

System presents the project creation experience.

03

User provides the required project information.

04

User submits the project.

05

System validates the request.

06

System creates the project.

07

User sees the project successfully created.

Decision point

Project name is missing.
BRD determines the rule.
User remains in the creation flow.

Alternate / error path

Validation fails.
System communicates the failure.
User can correct the input.

The UFD defines the behavioral sequence, not the visual treatment. That belongs to DSD.

Common flow elements

  1. 01

    Action

    Something the user or system does.

  2. 02

    Response

    How the system reacts to an action.

  3. 03

    Decision

    A point where the flow can branch.

  4. 04

    State

    The condition the system or user is currently in.

  5. 05

    Alternate Path

    A valid path different from the primary journey.

  6. 06

    Error Path

    A path caused by a failure or invalid condition.

  7. 07

    End State

    The outcome that concludes the journey.

08

How does AI use it?

The UFD gives the AI agent a behavioral sequence to implement. It tells the agent what happens before, during, and after a user action, including defined branches and outcomes.

UFD
Behavioral sequence

AI understands

  • Where the flow starts
  • What the user does
  • How the system responds
  • Where decisions occur
  • What alternate paths exist
  • How the flow ends

What

FSD

Rules

BRD

Behavior

UFD

Experience

DSD

Agent behavior

AI Instructions

The UFD does not tell the AI how the interface should visually look. It tells the AI what behavioral sequence the product must support.

09

How does it connect to other documents?

FSD

Create Project

“What capability exists?”

BRD

Project name is required

“What rule applies?”

UFD

User submits → validation → outcome

“How does the journey behave?”

DSD

“What should the user see and interact with?”

DDD / ASD / TAD

“How is it implemented?”

User flows translate functionality and rules into observable product behavior.

Feature

FEAT-004

Create Project

Rule

RULE-001

Project name is required

Flow

FLOW-001

Create Project

Screen

SCREEN-009

Later defined in DSD

10

Example

Feature concept

Create a Project

UFD perspective

The user starts from Projects, provides the required information, submits, the system evaluates the request, and the journey ends in a defined outcome.

PRD

Why

Users need a way to organize their work into projects.

FSD

What

Users can create a project.

BRD

Rules

The project creation process must follow defined rules.

UFD

Behavior

The user starts from Projects, provides the required information, submits, the system evaluates the request, and the journey ends in a defined outcome.

DSD

Experience

How the flow is represented in the interface.

DDD

Data

What information is stored.

ASD

Communication

How the client communicates.

TAD

Structure

How the capability is structured in the application.

DR

Order

When it should be implemented.

AI Instructions

Implementation

How the agent should implement the task.

11

UFD Template

ufd-template.md

# User Flow Document

## 01. Flow

### Flow ID
FLOW-001

### Flow Name

### Goal

### Actor

### Entry Point

### Preconditions

### Primary Flow

1.
2.
3.

### Decision Points

-

### Alternate Paths

-

### Error / Exceptional Paths

-

### End State

### Dependencies

---

## 02. Flow

Repeat as required.
12

Common mistakes

  • Turning the UFD into a screen-by-screen UI specification.
  • Showing only the happy path.
  • Ignoring alternate and error paths.
  • Describing business rules without showing where they affect the journey.
  • Defining visual design inside the flow.
  • Leaving the entry point or end state unclear.
  • Creating flows that don't correspond to actual product functionality.
  • Letting implementation details dictate the user journey.
  • Assuming undocumented states will be obvious to the implementer or AI.