patterns-flow-mapping

What this skill does

# Flow Mapping

## Overview

Connect multiple analyzed screenshots into coherent interaction flows by systematically inventorying screens, mapping navigation elements, identifying transitions, and assembling user journeys. Every screen must have defined entry and exit points, every gap must be explicitly noted, and every flow must be organized around user goals.

## When to Use

- Multiple screenshots of an app or site have been analyzed and need connecting into flows
- Building a navigation architecture from visual references
- Identifying how users move between screens in an existing product
- Documenting user journeys from screenshot evidence
- Auditing an existing flow for dead ends, orphaned screens, or missing states
- Preparing interaction specifications for implementation

## When NOT to Use

- Only a single screenshot is available (use `humaninloop:analysis-screenshot` instead)
- Designing flows from scratch without reference screenshots
- Working from wireframes or Figma prototypes where flows are already documented
- The task is purely visual design without navigation concerns

## Prerequisites

Each screenshot entering the flow mapping process should already have a completed analysis from `humaninloop:analysis-screenshot`. If screenshots have not been analyzed, complete that step first.

**REQUIRED:** Run `humaninloop:analysis-screenshot` on each screenshot before beginning flow mapping.

## Step 1: Screen Inventory

Catalog every available screenshot before mapping any connections.

### Process

1. **List every screenshot** -- Assign each a short identifier (e.g., `S01-home`, `S02-profile`, `S03-settings`).
2. **Classify each screen** -- Determine what state or view it represents.
3. **Identify screen type** -- Categorize by function.
4. **Note platform** -- Confirm the navigation paradigm (mobile, web, desktop).

### Screen Type Classification

| Type | Description | Examples |
|------|-------------|---------|
| Landing | Entry point, first impression | Splash, onboarding, login |
| Hub | Navigation center, many exit points | Home, dashboard, main tab |
| Task | Focused on completing an action | Checkout, compose, form |
| Detail | Displays information about an entity | Profile, product page, article |
| Utility | Settings, preferences, auxiliary | Settings, help, about |
| Overlay | Appears above another screen | Modal, bottom sheet, dialog |
| Transitional | Brief state between actions | Loading, success confirmation |

### Output Format

```
SCREEN INVENTORY:
  Total screenshots: [N]
  Platform: [mobile-ios / mobile-android / web-desktop / web-responsive / desktop-app]
  Navigation paradigm: [tab-bar / sidebar / hamburger / breadcrumb / URL-based / mixed]

  ID          | Type         | Screen Name           | Key Content
  ------------|--------------|----------------------|------------------
  S01-home    | Hub          | Home Feed             | Feed, nav bar, FAB
  S02-profile | Detail       | User Profile          | Avatar, stats, posts
  S03-login   | Landing      | Login                 | Email, password, social
  ...

IDENTIFIED GAPS:
  - No screenshot for [expected screen, e.g., "registration flow"]
  - Missing [state type, e.g., "empty state for home feed"]
  - No screenshot showing [transition, e.g., "search results"]
```

Always document gaps. A complete inventory includes explicit acknowledgment of what is missing.

## Step 2: Navigation Mapping

For each screen, identify every interactive element that causes navigation.

### Process

1. **Scan each screen** -- Identify all tappable, clickable, or swipeable elements.
2. **Classify the navigation element** -- Tab, button, link, gesture, menu item, breadcrumb, back arrow.
3. **Determine destination** -- Where does each element lead? Map to a screen ID from the inventory. If the destination is not in the inventory, mark it as `UNKNOWN-[description]`.
4. **Note element location** -- Top bar, bottom bar, inline, floating.

### Platform-Specific Navigation Elements

| Platform | Common Elements |
|----------|----------------|
| Mobile (iOS) | Tab bar, navigation bar back button, swipe gestures, pull-to-refresh, floating action button, bottom sheet trigger |
| Mobile (Android) | Bottom navigation, navigation drawer/hamburger, FAB, top app bar, system back button |
| Web | Top nav links, sidebar menu, breadcrumbs, URL routing, footer links, logo-home link |
| Desktop | Menu bar, sidebar tree, toolbar buttons, keyboard shortcuts, context menus |

### Output Format

```
NAVIGATION MAP:

Screen: S01-home
  Element               | Type      | Location    | Destination
  ----------------------|-----------|-------------|------------------
  Profile avatar        | Button    | Top-right   | S02-profile
  Tab: Search           | Tab       | Bottom bar  | UNKNOWN-search
  Settings gear         | Icon btn  | Top-left    | S03-settings
  Feed item tap         | List item | Content     | UNKNOWN-post-detail
  FAB (+)               | FAB       | Bottom-right| UNKNOWN-compose
  Pull down             | Gesture   | Content     | S01-home (refresh)

Screen: S02-profile
  Element               | Type      | Location    | Destination
  ----------------------|-----------|-------------|------------------
  Back arrow            | Button    | Top-left    | [previous screen]
  Edit Profile          | Button    | Inline      | UNKNOWN-edit-profile
  Tab: Posts             | Tab       | Content     | S02-profile (tab)
  Tab: Likes            | Tab       | Content     | S02-profile (tab)
```

## Step 3: Transition Identification

Document how users move between screens, what triggers each transition, and what data carries across.

### Transition Properties

For each connection between screens, capture:

| Property | Description |
|----------|-------------|
| Trigger | What action initiates the transition (tap, swipe, submit, timer) |
| Animation type | Push (slide), modal (rise), fade, tab switch, replace, none |
| Direction | Forward (deeper), backward (return), lateral (sibling), overlay |
| Data carried | What information passes to the next screen (user ID, search query, selected item) |
| Reversibility | Can the user return? How? (back button, swipe back, close button, system back) |
| Conditions | Any prerequisites (authentication, completed form, network availability) |

### Output Format

```
TRANSITIONS:

  FROM          → TO              | Trigger          | Type    | Direction | Data Carried
  ------        → ------          | -------          | ----    | --------- | -----------
  S01-home      → S02-profile     | Tap avatar       | Push    | Forward   | user_id
  S02-profile   → S01-home        | Back arrow       | Pop     | Backward  | none
  S01-home      → S03-settings    | Tap gear icon    | Push    | Forward   | none
  S01-home      → UNKNOWN-compose | Tap FAB          | Modal   | Overlay   | none
  S03-settings  → UNKNOWN-theme   | Tap "Theme"      | Push    | Forward   | current_theme

CONDITIONAL TRANSITIONS:
  S03-login → S01-home: Requires successful authentication
  UNKNOWN-compose → S01-home: Requires post submission (or cancel)
```

## Step 4: User Journey Construction

Assemble screens into named journeys organized around user goals.

### Process

1. **Identify user goals** -- What does a user come to this app to accomplish? (browse content, make a purchase, update profile, onboard).
2. **Trace the path** -- For each goal, trace the screen sequence from entry to completion.
3. **Name the journey** -- Use goal-oriented naming (not screen-oriented).
4. **Mark start and end** -- Every journey has a clear beginning and defined completion state.
5. **Note decision points** -- Where does the user choose between paths?
6. **Note failure paths** -- What happens if the user fails at a step? (wrong password, network error, validation failure).

### Output Format

```
USER JOURNEYS:

Journey: First-Time Onboarding
  Goal: New user creates account and reaches home feed
  Start: S03-login