Skip to content
Skillsheet

journey-driven-implementation

journey-driven-implementation

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
Category: implementation
  • user-journey
  • requirements
  • vertical-slice
  • walking-skeleton
  • scope
  • journey-map

Install this skill

npx . --tool claude-code --only journey-driven-implementation

Run from a git checkout of this repo — see the README for details.

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