User story mapping

This is the exact file agents read, including the credit header and licence notice. Save it as user-story-mapping/SKILL.md.

---
name: user-story-mapping
description: Build a user story map that lays a product out as the story of someone using it, then slice it into releases, using Jeff Patton's method. Carries the real rules: a backbone of user activities and steps as verb phrases read left to right with "then", details hung underneath by priority read with "or", one storyline rather than a flowchart, a mile-wide-inch-deep first pass to avoid map shock, a walking skeleton as the thin first slice, and release lines that each name a target user and a measurable outcome rather than being filled to capacity. Use it when someone says build a story map, map the user journey, what goes in the MVP, slice this into releases, or our backlog is a flat list. Do NOT use it to rank a written backlog (see prioritisation-frameworks), to set now-next-later horizons or communicate the plan (see product-roadmapping), or to choose which problem to solve (see opportunity-solution-trees).
---

# User story mapping

A user story map lays a product out as the story of someone using it. Across the top runs the backbone: the activities and steps a user moves through in the order they happen, read left to right like a sentence. Down each step hang the details, the smaller stories, ordered by priority. Horizontal lines cut the map into releases, and the thinnest end-to-end path through it is the walking skeleton. The technique comes from Jeff Patton, and its purpose is to keep a whole team looking at the user's journey while they decide what to build first, instead of arguing over a flat backlog.

This skill makes an AI agent build a story map from a real user journey, slice it into releases that each serve a named user and a measurable outcome, and find the thin first slice worth shipping. It shapes and slices the work. It does not rank a backlog that is already written, it does not set long-range horizons, and it does not choose which customer problem to solve. Ranking is the prioritisation-frameworks skill. Horizons and stakeholder communication are product-roadmapping. Choosing the problem from customer evidence is opportunity-solution-trees.

## When to use this skill, and when not to

Use it when a team needs to break a large feature or product into buildable pieces without losing the big picture, plan a minimum viable release, reorganise a messy backlog around the user's journey, or get product, design and engineering looking at the same picture. Use it when someone says build a story map, map the user journey, what goes in the MVP, slice this into releases, our backlog is a flat list, or we keep building features that do not add up to a usable product.

Do not use it to score or rank items that are already listed; that is the prioritisation-frameworks skill. Do not use it to lay out work across now-next-later horizons or to communicate direction to stakeholders; that is product-roadmapping. Do not use it to decide which customer problem is worth solving in the first place; that is opportunity-solution-trees, and a story map is best built after the problem is chosen. Do not use it when nobody can describe how a user actually moves through the product, because a map built on guesswork will slice the wrong things.

## What the agent needs from you before starting

Ask for these before building the map. Do not proceed on assumptions.

1. The user and their goal. Who is travelling through this journey, and what are they trying to get done, stated as an end state such as "file an expense claim" rather than a feature name.
2. The scope. Whether the map covers a whole product, one feature, or one section. A map with no stated scope sprawls until it is abandoned.
3. The journey, or the evidence for it. A walk-through from a user, a recording, a support flow, research notes, or at least a product person who can narrate the real steps. If nobody can tell the end-to-end story, say so and ask for that first.
4. The target outcome for the first release. The measurable change the first slice should produce, such as "a new user completes their first claim without support".

If the goal, the journey or the first-release outcome is missing, stop and ask. Do not invent user steps the team has not seen or cannot confirm.

## How to build a user story map, step by step

Follow these in order. The order is the point: the backbone before the detail, the detail before the slicing.

### Step 1. Frame the goal, the user and the scope

Write one line naming the user, their goal and the scope of the map. This is the frame everything hangs on. If two user types travel very different journeys, pick the primary one for this map and note the other rather than stacking both into one tangle.

### Step 2. Lay the backbone left to right

Write the user's activities and steps as short verb phrases, one per card, and place them across the top in the order they happen. Test the backbone by reading it aloud with "then" between the cards: "search for a flight, then choose a fare, then enter passengers, then pay". If it does not read as a sentence, the order or the wording is wrong. Keep this pass high level: get from the beginning of the journey to the end before adding any detail. Patton calls this going a mile wide and an inch deep.

### Step 3. Hang the details underneath, by priority

Under each step, add the smaller stories, options and variations as cards, stacked vertically with the highest priority at the top. Read a column downward with "or" between the cards: "pay by card, or pay by wallet, or pay on account". Keep concurrent users and edge cases as vertical variations under the one storyline. Do not split them into separate maps and do not turn the map into a flowchart of branches; a story map tells one typical flow and shows alternatives below it.

### Step 4. Walk the map and find the gaps

Read the whole map as the user. At each step ask what they would do next, what could go wrong, and what they would need to know. Add the missing cards. Repeat the walk for any secondary user type. This is where a map earns its keep: it surfaces steps a feature list never would.

### Step 5. Find the walking skeleton

Mark the thinnest path across the whole backbone that still lets the target user get from beginning to end. One card per step, the simplest version of each. This is the walking skeleton, and it is the first thing worth building, because it proves the journey works end to end before any step is made rich.

### Step 6. Slice releases against an outcome, not to capacity

Draw a horizontal line. For the release above it, name the target user and the measurable outcome it must produce, then keep only the cards needed to hit that outcome and push everything else below the line. Do not fill a release to the team's capacity; fill it to the outcome and stop. Thin and split the cards that remain above the line so the release stays as small as the outcome allows. Each later release gets its own line, its own target user and its own outcome.

### Step 7. Prune and hand off

Remove cards the team has decided it does not need rather than leaving them on the map "just in case", or move them to a parked area off the map. When a near-term release is agreed, pass only those cards into the delivery tool in small batches. Steps on the backbone usually become epics or features; the detail cards become stories or tasks with acceptance criteria. Ranking those stories is the prioritisation-frameworks skill; sequencing releases across horizons is product-roadmapping.

### Step 8. Run the readiness test

Before handing the map over, read the backbone end to end one more time. If you cannot tell a clear, continuous story of how the user reaches their goal, the map is not ready and the team is not ready to build the feature. Go back to the backbone before writing another story.

## Worked example

Goal handed over: "let a new user file their first expense claim." Scope: the claim-filing feature. User: a first-time employee claimant.

The agent lays a backbone of seven steps, read with "then": open the app, start a claim, add an expense, attach a receipt, categorise it, review the total, then submit. Under "attach a receipt" it hangs details by priority: photograph a receipt, or upload a file, or forward an email. Walking the map as the user surfaces two missing steps, "handle a rejected receipt" and "save a draft", which are added as cards.

The walking skeleton is the thinnest path: open, start, add one expense, photograph one receipt, submit, no categories, no drafts. Release one is sliced against the outcome "a new claimant submits a first claim without contacting support": it keeps the skeleton plus basic validation and drops categories, drafts and bulk upload below the line. Release two takes the outcome "claimants file a full month unaided" and pulls up categories and drafts. The agent hands the release-one cards to the delivery tool and notes that final scope is the team's to confirm.

## Templates you can use verbatim

Map, as indented text any tool can hold:

```
USER + GOAL: <who> wants to <end state>    SCOPE: <whole product | feature | section>
BACKBONE (left to right, read with "then"):
  [Activity] <group of steps toward a sub-goal>
    Step 1 <verb phrase>  |  Step 2 <verb phrase>  |  Step 3 <verb phrase>  ...
DETAILS (under each step, top = highest priority, read with "or"):
  Step 2: <detail a> / <detail b> / <detail c>
RELEASE 1  (target user: <...>  outcome: <measurable>)  <-- line
  <only the cards needed to hit the outcome; the walking skeleton sits here>
RELEASE 2  (target user: <...>  outcome: <measurable>)  <-- line
  <the next thinnest set>
```

Release-slice card:

```
Release: <n>
Target user: <segment>
Outcome it must produce: <measurable change>
In this slice: <cards needed to hit the outcome>
Deferred below the line: <everything not needed yet>
Walking skeleton covered? <yes/no>
```

Backbone check prompt, to run on the top row: "Read left to right with 'then' between each card. Does it tell one continuous user story from start to goal? If a card is a noun or a feature name rather than something the user does, rewrite it as a verb phrase."

## Common mistakes and how to avoid them

1. Losing the story. The map becomes a list of nouns, which is a feature breakdown, not a story. Spot it when cards name components instead of user actions. Fix it by naming the user, setting a start and an end, and writing every backbone card as a short verb phrase.
2. Map shock from too much detail too early. Breaking steps down before the backbone is complete produces hundreds of cards nobody can read. Spot it when the map is deep in one area and empty in others. Fix it by going a mile wide and an inch deep first, then adding detail.
3. Turning the map into a flowchart. Teams argue the one correct order, add every branch, or split parallel users into separate maps. Spot it when arrows and conditionals appear. Fix it by telling one typical flow left to right and showing variations vertically.
4. Releases sliced to capacity, not to an outcome. The team fills each release until the sprint is full. Spot it when a release has no stated user or measurable result. Fix it by naming the target user and outcome for each release and cutting everything not needed to reach it.
5. Building the map alone, then treating it as final. One person drafts it and the team reads it as a finished plan. Spot it when only one role was in the room. Fix it by building the map with product, design and engineering together, and by pruning stale cards rather than hoarding them.

## Quality bar: check the output against this before handing it over

- The map names one user, their goal and a scope in a single frame line.
- The backbone reads left to right as a continuous story with "then" between cards, and every backbone card is a verb phrase, not a noun or a feature name.
- Detail cards sit under their step, ordered by priority, read downward with "or", on one storyline rather than branching flowcharts.
- A walking skeleton is marked: the thinnest end-to-end path through the backbone.
- Every release line names a target user and a measurable outcome, and holds only the cards needed to hit it.
- No user step is invented that the team has not seen or cannot confirm.
- A note tells the human that the final release scope is theirs to confirm, and ranking and sequencing are handed to the named sibling skills.

## Guardrails

- Irreversible actions need a human. Committing a release scope, moving cards into the delivery tool, or telling stakeholders what ships when are decisions for a person. The skill proposes the slice and the skeleton and asks for confirmation before anything is locked.
- Never fabricate the journey. If nobody can describe how the user moves through the product, the honest output is "map the real journey with a user first", not a plausible-looking invented map.
- Protect user data. If the map draws on real user recordings, personas or research, do not paste names, emails or other personal details onto the cards. Describe the user by segment and keep raw research where it lives.
- Mind the cost. A story map is a workshop that takes people's time. Keep the first pass a mile wide and an inch deep so the session produces a usable backbone rather than map shock.
- Stay in scope. This skill shapes and slices the journey. It does not rank stories (prioritisation-frameworks), set horizons or communicate the plan (product-roadmapping), or choose the problem (opportunity-solution-trees). Hand off to those skills by name.

## Tool-specific appendix

The core method is tool-agnostic: the map is a backbone, details and release lines, and the indented-text template holds it anywhere. On a physical or virtual wall (sticky notes, FigJam, Miro, or similar), put activities and steps across the top, details in columns beneath, and release lines as horizontal dividers, and build it with the team in the room rather than alone. In a dedicated story-mapping tool (StoriesOnBoard, Avion, or similar) the backbone and release slices are first-class, so use them and resist the pull to manage the live map inside a ticket tracker, where reordering is slow and parked cards pile up. When a release is agreed, export only those cards into the delivery tool in small batches. Whatever the tool, the steps above do not change; the tool only decides how the map is drawn and where agreed cards go next.

## Sources

- Jeff Patton, "User Story Mapping" and "Why Map User Stories; How to Map User Stories" (the backbone, the narrative flow, slicing a map into viable releases), jpattonassociates.com. Last verified 11 November 2026.
- Jeff Patton, "5 Story Mapping Mistakes" (losing the story, map shock, flowcharting, mapping the whole product for one feature, releases not anchored to outcomes), jpattonassociates.com/5-story-mapping-mistakes. Last verified 11 November 2026.
- Jeff Patton interview, "Getting started with User Story Mapping", Mind the Product (thin slices, releases to an outcome, shared understanding over documents), mindtheproduct.com. Last verified 11 November 2026.
- Mike Cohn, "User Story Mapping: how to create story maps", Mountain Goat Software (read across with "then", down with "or", finding the backbone, slicing releases), mountaingoatsoftware.com. Last verified 11 November 2026.
- Nielsen Norman Group, "User Story Mapping" (activities, steps, details; relation to journey maps; when to use), nngroup.com/articles/user-story-mapping. Last verified 11 November 2026.
- Zarar Siddiqi, "5 Story Mapping Anti-Patterns" (building the map alone, work breakdown instead of a map, skipping release cuts, managing in Jira, stale stickies), bitbytebit.substack.com. Last verified 11 November 2026.

---
1.0.0, 11 November 2026: first release. Use, adapt and share this skill under CC BY 4.0: credit Afeez Adebayo, link afeezadebayo.com and the skill's download page. This is decision-support guidance, not a substitute for mapping the journey with your own users.