Skip to content

User Journey Map

Purpose

User Journey Map is the frame-level experience artifact, and it is optional. Its unique job is to show the whole experience a task involves, including steps outside the product, so the team can see where the stories cover the experience, where they leave gaps, and which opportunities it owns.

It is not a story, a user flow or a design. Stories own testable behavior; the user flow owns views and transitions; wireframes own layout and states. The map links to them by ID.

Example

Show a worked example of this artifact
---
ddx:
  id: example.user-journey-map.depositmatch.import-weekly-files
  authoring:
    home: repo
  depends_on:
    - example.feature-specification.depositmatch.csv-import
    - example.user-story.depositmatch.upload-csv
---

# UJM-001: Import a Client's Weekly Files

**Feature**: [[FEAT-001]] CSV Import and Column Mapping | **Map kind**: future-state | **Evidence**: research plan `pilot-reviewer-interviews` (6 interviews), pilot support tickets

## Actor and Scenario

- **Person**: Reconciliation lead. Reconciles 12 to 20 clients a week on a desktop; knows each client's books, not their export formats.
- **Task**: Import a client's weekly files (FEAT-001 Task Model).
- **Scenario**: Monday's bank and invoice exports for Acme Dental arrive by email. Maya brings them into DepositMatch, checks the columns and the rejected rows, and confirms the import so matching can start.
- **Trigger**: The client's weekly exports arrive.
- **End state**: The import is confirmed and match suggestions are ready, or Maya knows exactly what to ask the client to fix.

### Goals and Expectations

- Finish each client's import in under five minutes.
- Never let a wrong column produce plausible-looking matches.
- Know before matching which rows were left out and why.

## Journey Phases

| Phase | Actions | Thoughts | Emotion | Touchpoints | Stories / ACs |
|---|---|---|---|---|---|
| Receive | Saves the two attachments from the client's email | "Same format as last week, I hope." | neutral: routine | Email (outside the product) | uncovered: happens outside DepositMatch |
| Upload | Starts a new import and attaches both files | "Did it take both?" | neutral: brisk | upload | US-001-AC1, US-001-AC2 |
| Check columns | Confirms the saved mapping, fixes one renamed column | "If amount is wrong, every match is wrong." | negative: wary | mapping review | US-002-AC1, US-002-AC2 |
| Review rejections | Reads why 14 rows were rejected | "Are these mine to fix or the client's?" | negative: unsure | validation results | US-003-AC1 |
| Confirm | Confirms the import and moves to matching | "Good, that's done." | positive: relieved | import summary | US-003-AC2 |
| Follow up | Emails the client about the rejected rows | "They'll want the row numbers." (assumption) | neutral | Email (outside the product) | uncovered: no story exports the rejected rows |

## Insights

| Insight | Phase | Evidence |
|---|---|---|
| A renamed column is the most common reason an import goes wrong | Check columns | 4 of 6 interviews; 9 pilot support tickets |
| Reviewers copy rejected rows by hand into an email to the client | Follow up | 5 of 6 interviews |

## Opportunities

| Opportunity | Phase | Owner | Metric | Target |
|---|---|---|---|---|
| Flag a saved mapping whose column was renamed, before the reviewer confirms | Check columns | Import squad | Imports corrected after confirmation | hypothesis: under 1% |
| Export rejected rows with their row numbers and reasons | Follow up | Product | Median time from summary to client email | hypothesis: under 2 minutes |

## Story Coverage

| Phase | Covered by | Gap |
|---|---|---|
| Upload to Confirm | US-001, US-002, US-003 | None |
| Follow up | none | No story exports the rejected rows |

Reference

ActivityFrame — Define what the system should do, for whom, and how success will be measured.
Default locationdocs/helix/01-frame/journey-maps/UJM-{n}-{name}.md
RequiresNone
EnablesNone
InformsUser Flow
Solution Design
Story Test Plan
Improvement Backlog
Generation prompt
Show the full generation prompt
# User Journey Map Generation Prompt

Map one person's experience of one task, phase by phase, and trace each phase
to the acceptance criteria that deliver it.

## Purpose

User Journey Map is the **frame-level experience artifact**, and it is
optional. Its unique job is to show the whole experience a task involves,
including steps outside the product, so the team can see where the stories
cover the experience, where they leave gaps, and which opportunities it owns.

It is not a story, a user flow or a design. Stories own testable behavior; the
user flow owns views and transitions; wireframes own layout and states. The map
links to them by ID.

## Focus

- Create `docs/helix/01-frame/journey-maps/UJM-XXX-[name].md` only when a task
  spans several stories or views and the team needs the whole picture.
- Pick one person from the PRD's User Segments and one task from the feature
  specification's Task Model, and name both. If the PRD has no User Segments
  or the feature has no Task Model, name the person and the task in plain words
  from the PRD's users and the feature's stories instead. A second person or
  task is a second map.
- State goals and expectations before the phases; phases are judged against
  them.
- Name phases as the person's stages ("Notice", "Prepare", "Decide"), not as
  views. Include steps outside the product, such as an email or a phone call.
- Per phase, write the actions, the person's thoughts in their words, one
  emotion (positive, neutral or negative, plus a word) and the touchpoints.
- Ground thoughts and emotions in evidence: a research plan's findings,
  support data or analytics. Mark ungrounded entries "(assumption)". Do not
  invent research.
- Trace every in-product phase to `US-<n>-AC<m>` IDs. Mark a phase no
  criterion delivers as `uncovered:` with a reason; that gap is a finding.
- Give every opportunity one owner and the metric that shows its effect. A
  target is optional: label it a hypothesis unless evidence supports it, and do
  not turn it into a delivery or release gate.
- Name rows by what they say; do not number insights or opportunities.

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| The person's phases, thoughts, emotions, insights, opportunities | User Journey Map |
| The tasks a feature supports | Feature Specification (Task Model) |
| Testable behavior and Given/When/Then criteria | User Stories |
| Views, transitions and alternate paths | User Flow |
| Layout, states and events of one view | Wireframe |
| Ranked follow-up work | Improvement Backlog |

## Completion Criteria

- One person and one task, with a scenario, goals and expectations.
- Phases run from trigger to end state.
- Every in-product phase names its acceptance criteria or is marked uncovered.
- Every thought and emotion cites evidence or is marked as an assumption.
- Every opportunity has one owner and one metric; any target is supported or labelled a hypothesis.
Template
Show the template structure
---
ddx:
  id: UJM-XXX
  authoring:
    home: repo
  depends_on:
    - FEAT-XXX
    - US-XXX
---

# UJM-XXX: [Journey Name]

**Feature**: [[FEAT-XXX]] | **Map kind**: [current-state | future-state] | **Evidence**: [research plan, support data, analytics, or "assumption-based"]

## Actor and Scenario

- **Person**: [PRD user segment, or the PRD user if it has no segments: role, context, a relevant constraint such as device, expertise or access]
- **Task**: [The Task Model row in FEAT-XXX this journey carries out, by name, or the task in plain words if the feature has no Task Model]
- **Scenario**: [What happens, from trigger to end state, in one or two sentences]
- **Trigger**: [The event that starts the journey]
- **End state**: [What is true when the person is done]

### Goals and Expectations

- [What the person is trying to achieve, in their terms]
- [What they expect to happen: time, effort, feedback, control]

## Journey Phases

<!-- Phases are the person's stages, not views. Include steps outside the
product. Emotion: positive / neutral / negative, plus a word. Mark ungrounded
thoughts and emotions "(assumption)". -->

| Phase | Actions | Thoughts | Emotion | Touchpoints | Stories / ACs |
|---|---|---|---|---|---|
| [Phase name] | [What the person does] | ["What they think", in quotes] | [positive / neutral / negative: word] | [Channel, or a user-flow view] | [US-XXX-AC1, or "uncovered: reason"] |

## Insights

<!-- Pain points and moments that matter, each with its evidence. -->

| Insight | Phase | Evidence |
|---|---|---|
| [Pain point or moment that matters] | [Phase] | [Research plan finding, support data, or "assumption"] |

## Opportunities

<!-- Each opportunity has one owner and one metric. A target is optional:
label it a hypothesis unless evidence supports it. It is not a delivery gate. -->

| Opportunity | Phase | Owner | Metric | Target |
|---|---|---|---|---|
| [What to change or add] | [Phase] | [Role or team] | [Metric; link its metric definition if one exists] | [Supported target, a hypothesis, or none] |

## Story Coverage

| Phase | Covered by | Gap |
|---|---|---|
| [Phase] | [US-XXX: AC IDs] | [None, or what no story delivers yet] |
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/frame/user-journey-map.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:2dd9e37e…c6edbd65

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/frame/user-journey-map/",
        "digest": {
          "alg": "sha256",
          "value": "2dd9e37e96b727273541b25a804b4ee9dbb76ce1dcc6391280224d62c6edbd65"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "OUm7jDWJLZYacumeHEhvakKbCgho4QatUVPZNI3lLwK6CGdlQIIa83q4lcDhKcMkXj22Zhx4evKiSlq-P084Bg",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}