---
name: journey-driven-implementation
description: Builds the user journey from a requirement first — actors, steps, states, and failure paths as an explicit map — then implements it as vertical end-to-end slices, one journey step per slice. Use when turning a requirement, PRD, or feature request into working software, when scope needs cutting, or when the user mentions user journeys, journey mapping, or walking a story end-to-end.
category: implementation
keywords: user-journey, requirements, vertical-slice, walking-skeleton, scope, journey-map
---

# Journey-Driven Implementation

A requirement is a claim about value; a user journey is the proof path that claim must survive. Map the journey before writing code, then implement the journey — not the layers — as vertical slices: each slice completes one journey step through UI, logic, and data together. The journey map is the plan, the build order, and the test plan in one artifact.

## When to apply

Use when implementing a feature from a requirement, ticket, or PRD; when a request is vague enough that "what does the user actually do?" hasn't been answered; or when scope keeps growing and someone needs to decide what ships first.

## Workflow

1. **Extract the requirements** — from the request, identify each **actor** (who), their **goal** (what they want), and the **outcome** (how they know it worked). Separate functional from non-functional needs. Done when every requirement fits one sentence: *"As <actor>, I can <do X> so that <outcome>."*
2. **Map the journey** — for each actor/goal, list the steps from entry to outcome. For each step record:
   - what the user sees and does (UI)
   - what the system does in response (logic)
   - what data is read or written (data)
   - the states it can land in: **empty, loading, success, error, unauthorized**
   The happy path first, then the failure paths — errors users will actually hit, not every conceivable one.
3. **Groom the map** — mark the **walking skeleton**: the thinnest end-to-end path that delivers the outcome in its crudest form. Cut steps that don't serve the outcome into a later increment. Scope is decided here, once, against the map — not renegotiated mid-build.
4. **Slice vertically** — implement one journey step per slice, all the way through UI → logic → data. The first slice *is* the walking skeleton: real but minimal, end-to-end, deployed or at least demonstrable. Horizontal layers ("build all the API, then all the UI") are how features die half-wired.
5. **Verify against the map** — walk the journey as the user would: every step demonstrably works on the happy path, and each step's mapped states behave as written (the error really shows, the empty state really renders). Each journey step doubles as a verification case; wire the important ones as automated tests.
6. **Update the map, then the code** — when requirements shift mid-build, revise the journey map first and let the diff show which slices change. The map is the single source of truth; code drifts, maps don't.

## Rules

- No step without a journey step — a feature you can't place on the map ("what screen is this on?") is scope creep; add it to the map deliberately or not at all.
- The journey reveals the architecture — let the steps and states dictate the modules, not the other way around.
- Vertical over horizontal — a slice that's thin the whole way through beats a layer that's deep but dead-ended.
- States are requirements — a step isn't done when the happy path works; it's done when its empty, loading, error, and unauthorized states behave as mapped.
- The map outlives the ticket — keep it updated; it's the artifact the next person reads to understand why the feature looks like this.

## Related skills

- [ui-backend-integration](/skills/ui-backend-integration) — how to wire each vertical slice's loading, success, and error states.
- [test-to-completion](/skills/test-to-completion) — closing the verification loop on each slice.
- [lean-implementation](/skills/lean-implementation) — keeping every slice as small as the journey allows.