design-protocol 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +225 -0
  3. package/agents/dp-researcher.md +239 -0
  4. package/agents/dp-verifier.md +207 -0
  5. package/bin/install.js +464 -0
  6. package/commands/dp-back.md +221 -0
  7. package/commands/dp-discuss.md +257 -0
  8. package/commands/dp-execute.md +513 -0
  9. package/commands/dp-journey.md +85 -0
  10. package/commands/dp-progress.md +178 -0
  11. package/commands/dp-roadmap.md +83 -0
  12. package/commands/dp-skip.md +186 -0
  13. package/commands/dp-start.md +510 -0
  14. package/commands/dp-storytell.md +94 -0
  15. package/commands/dp-verify.md +207 -0
  16. package/package.json +59 -0
  17. package/skills/dp-color/SKILL.md +214 -0
  18. package/skills/dp-color/export_tokens.py +297 -0
  19. package/skills/dp-color/references/apca-contrast.md +87 -0
  20. package/skills/dp-color/references/hue-emotions.md +109 -0
  21. package/skills/dp-color/references/oklch-gamut.md +79 -0
  22. package/skills/dp-color/references/pitfalls.md +171 -0
  23. package/skills/dp-color/references/scale-patterns.md +206 -0
  24. package/skills/dp-color/references/tool-workflows.md +200 -0
  25. package/skills/dp-discovery/SKILL.md +480 -0
  26. package/skills/dp-eng_review/SKILL.md +471 -0
  27. package/skills/dp-eng_review/references/code-review-checklist.md +385 -0
  28. package/skills/dp-eng_review/references/react-patterns.md +512 -0
  29. package/skills/dp-eng_review/references/shadcn-patterns.md +510 -0
  30. package/skills/dp-eng_review/references/tailwind-conventions.md +351 -0
  31. package/skills/dp-journey/SKILL.md +682 -0
  32. package/skills/dp-journey/references/journey-types.md +97 -0
  33. package/skills/dp-journey/references/map-structures.md +177 -0
  34. package/skills/dp-journey/references/omnichannel-patterns.md +208 -0
  35. package/skills/dp-journey/references/research-methods.md +125 -0
  36. package/skills/dp-prd/SKILL.md +201 -0
  37. package/skills/dp-prd/references/claude-code-spec.md +107 -0
  38. package/skills/dp-prd/references/interview-questions.md +158 -0
  39. package/skills/dp-prd/references/section-templates.md +231 -0
  40. package/skills/dp-research/SKILL.md +540 -0
  41. package/skills/dp-research/references/facilitation-guide.md +291 -0
  42. package/skills/dp-research/references/interview-guide-template.md +190 -0
  43. package/skills/dp-research/references/method-selection.md +195 -0
  44. package/skills/dp-research/references/question-writing.md +244 -0
  45. package/skills/dp-research/references/research-report-template.md +363 -0
  46. package/skills/dp-research/references/synthesis-methods.md +289 -0
  47. package/skills/dp-research/references/usability-test-template.md +260 -0
  48. package/skills/dp-roadmap/SKILL.md +648 -0
  49. package/skills/dp-roadmap/references/prioritization-frameworks.md +312 -0
  50. package/skills/dp-roadmap/references/roadmap-structures.md +179 -0
  51. package/skills/dp-roadmap/references/roadmap-workshops.md +264 -0
  52. package/skills/dp-roadmap/references/theme-development.md +168 -0
  53. package/skills/dp-storytell/SKILL.md +645 -0
  54. package/skills/dp-storytell/references/audience-playbooks.md +260 -0
  55. package/skills/dp-storytell/references/content-type-templates.md +310 -0
  56. package/skills/dp-storytell/references/delivery-tactics.md +228 -0
  57. package/skills/dp-storytell/references/narrative-frameworks.md +259 -0
  58. package/skills/dp-ui/SKILL.md +503 -0
  59. package/skills/dp-ui/references/b2b-enterprise-patterns.md +319 -0
  60. package/skills/dp-ui/references/data-visualization.md +304 -0
  61. package/skills/dp-ui/references/visual-design-principles.md +237 -0
  62. package/skills/dp-ux/SKILL.md +414 -0
  63. package/skills/dp-ux/references/accessibility-checklist.md +128 -0
  64. package/skills/dp-ux/references/product-excellence.md +149 -0
  65. package/skills/dp-ux/references/usability-principles.md +140 -0
  66. package/skills/dp-ux/references/ux-patterns.md +221 -0
  67. package/templates/config.json +55 -0
  68. package/templates/context.md +96 -0
  69. package/templates/project.md +83 -0
  70. package/templates/requirements.md +137 -0
  71. package/templates/roadmap.md +168 -0
  72. package/templates/state.md +107 -0
@@ -0,0 +1,682 @@
1
+ ---
2
+ name: dp-journey
3
+ description: >
4
+ Build customer journey maps, service blueprints, and omnichannel experience maps using NNGroup's
5
+ methodology (Kaplan, Salazar, Gibbons, Kaley). Trigger for "/dp:journey", journey map, customer
6
+ journey, experience map, service blueprint, touchpoint map, omnichannel journey, CX journey,
7
+ onboarding journey, journey management. Optional Phase 1.5b of DP workflow — runs between
8
+ Discovery and UX, parallel to PRD. Produces research-grounded journey artifacts with
9
+ actor/scenario, phases, actions, thoughts, emotions, pain points, and opportunities.
10
+ ---
11
+
12
+ # Journey Mapping & Experience Design
13
+
14
+ Create journey artifacts that align cross-functional teams around the *customer's* experience — not the organization's. Grounded in NNGroup's five-principle framework: shared vision, customer focus, collaborative, research-based, iterative.
15
+
16
+ ---
17
+
18
+ ## When to Use This Skill
19
+
20
+ Run `/dp:journey` when you need to:
21
+
22
+ - **Understand an existing experience** — map the current-state journey based on research
23
+ - **Envision a new experience** — design the future-state journey before UX details
24
+ - **Diagnose painful moments** — find the worst part of a multi-step experience
25
+ - **Align stakeholders** — create a shared artifact for a cross-functional team
26
+ - **Design across channels** — coordinate web, mobile, email, in-person, phone, chat
27
+ - **Extend a journey into operations** — use a service blueprint to align frontstage + backstage
28
+
29
+ **Don't use this skill for:**
30
+ - Single-screen UX decisions — use `/dp:ux`
31
+ - Feature specs — use `/dp:prd`
32
+ - User flow diagrams — those are part of UX, not journey mapping (flows are UI-centric; journeys are human-centric)
33
+
34
+ ---
35
+
36
+ ## DP Workflow Integration
37
+
38
+ This skill is an optional sub-phase (Phase 1.5b) placed between Discovery and UX, parallel to PRD.
39
+
40
+ ### Detecting Workflow Mode
41
+
42
+ At the start of any `/dp:journey` invocation:
43
+
44
+ 1. **Check for `.design/config.json`**
45
+ 2. **If found** (workflow mode):
46
+ - Load `.design/config.json` for settings
47
+ - Load `.design/phases/DISCOVERY.md` for persona, problem, context
48
+ - Load `.design/phases/PRD.md` if it exists
49
+ - Load any research artifacts under `.design/research/` if research was run (e.g., `RESEARCH-PLAN.md`, `FINDINGS-*.md`) — this is where `/dp:research` writes, not under `phases/`
50
+ - Check for `.design/phases/01.5b-CONTEXT.md` if `/dp:discuss` was run first
51
+ - Announce: "Running journey mapping as part of DP workflow..."
52
+ 3. **If not found** (standalone mode):
53
+ - Run with default behavior
54
+ - Ask: "Are we mapping an existing journey (current-state) or designing a new one (future-state)?"
55
+
56
+ ### Pre-fill Rules (Workflow Mode)
57
+
58
+ | Field | Pre-fill Source | Interview Action |
59
+ |---|---|---|
60
+ | Actor / persona | DISCOVERY.md primary user | Confirm — only ask if ambiguous |
61
+ | Scenario | DISCOVERY.md problem statement | Refine — problem ≠ scenario |
62
+ | Goals & expectations | DISCOVERY.md user goals | Confirm |
63
+ | Known pain points | DISCOVERY.md + RESEARCH findings | Expand |
64
+ | Touchpoints / channels | DISCOVERY.md existing landscape | Ask for completeness |
65
+ | Research basis | RESEARCH files | Flag if none → "hypothesis mode" |
66
+
67
+ **Workflow mode summary message:**
68
+ ```
69
+ DP WORKFLOW ACTIVE
70
+ ────────────────────────────────────────────────────────────────────────────────
71
+ Project: [name]
72
+ Phase: 1.5b (Journey Mapping — optional)
73
+ Previous: Discovery (complete)
74
+ Next: UX (Phase 2)
75
+
76
+ Pre-filled from Discovery:
77
+ Actor ✓ Scenario ◐ Goals ✓ Touchpoints ◐
78
+ Research basis: [research artifacts found | NONE — hypothesis mode]
79
+
80
+ I'll confirm pre-filled sections and interview you on the gaps.
81
+ ────────────────────────────────────────────────────────────────────────────────
82
+ ```
83
+
84
+ ---
85
+
86
+ ## The Five NNGroup Principles (Kate Kaplan)
87
+
88
+ Every journey artifact this skill produces must honor these five principles — they double as process steps:
89
+
90
+ 1. **Establish the "why" and the "what"** — A map without a business goal becomes decoration. Define the decision it will drive before starting.
91
+ 2. **Base it on truth** — Ground the map in real qualitative research (interviews, observations, diary studies), supplemented by quantitative data. Assumption-based maps are dangerous. If research is missing, the skill enters **hypothesis mode** (see below) and flags every unverified claim.
92
+ 3. **Don't design in a vacuum** — Collaborate across functions (product, engineering, support, marketing, ops) during synthesis, not just review. Co-creation produces buy-in; presentation produces compliance.
93
+ 4. **Don't jump to visualization** — The insight work happens in synthesis. Visualizing too early locks in bad structure. Populate all swimlanes before styling the artifact.
94
+ 5. **Engage others with the artifact** — Treat the map as an *interactive, living document rather than static output*. Maps are tools for alignment and action, not deliverables to file.
95
+
96
+ **Hypothesis mode:** If no user research exists, the skill proceeds but prefixes every actions/thoughts/emotions entry with `[HYPOTHESIS]` and adds a "Validation Plan" section recommending research methods.
97
+
98
+ ---
99
+
100
+ ## Journey Artifact Types
101
+
102
+ The skill supports five distinct artifact types. Pick one per invocation based on the user's goal. These align with NNGroup's UX Mapping Cheat Sheet (Gibbons).
103
+
104
+ ### 1. Customer Journey Map (default)
105
+ **What it is:** One actor, one scenario, tied to a specific product or service, chronological, from the user's perspective.
106
+
107
+ **Use when:** Improving an existing experience or designing a specific product flow (e.g., "first-time buyer on mobile").
108
+
109
+ **Variants:**
110
+ - **Current-state** — how the journey works *today* (research-grounded, diagnostic)
111
+ - **Future-state** — how the journey *should* work (vision-setting, strategy)
112
+
113
+ **Structure:** Zone A (Actor/Scenario/Expectations) → Zone B (Phases + Actions + Thoughts + Emotions + Touchpoints) → Zone C (Opportunities + Ownership + Metrics).
114
+
115
+ ### 2. Experience Map
116
+ **What it is:** Broader than a journey map — a *generic* human perspective, not tied to a specific product or service. Describes how people experience a whole domain (e.g., "managing personal finances" or "planning a wedding").
117
+
118
+ **Use when:** Upstream discovery for a new product category; understanding context before a product exists; seeing competitive/substitute options.
119
+
120
+ **Structure:** Same swimlanes as journey map, but scenario is a life context spanning multiple providers.
121
+
122
+ ### 3. Day-in-the-Life Map
123
+ **What it is:** Plots actions/thoughts/emotions across a person's *whole day* (or wider context), not just a product-specific journey.
124
+
125
+ **Use when:** Finding new product opportunities; understanding competing priorities; designing for moments (not screens).
126
+
127
+ **Structure:** Timeline = hours of a day; swimlanes = activities, tools, emotions, unmet needs.
128
+
129
+ ### 4. Service Blueprint
130
+ **What it is:** NNGroup (Gibbons): *"a diagram that visualizes the relationships between different service components — people, props (physical or digital evidence), and processes — that are directly tied to touchpoints in a specific customer journey."* Extends the journey map *downward* into the organization.
131
+
132
+ **Use when:** The experience involves service delivery (humans, systems, handoffs) and internal coordination is the bottleneck. Banking, healthcare, hospitality, complex B2B SaaS onboarding, omnichannel retail.
133
+
134
+ **Structure:** 5 layers separated by 3 lines — see Service Blueprint Specifics below.
135
+
136
+ ### 5. Omnichannel Journey Map
137
+ **What it is:** A journey map where channel switching is first-class. Shows the same actor moving across web, mobile, email, phone, in-person, chat.
138
+
139
+ **Use when:** The experience spans 2+ channels and handoff quality matters (e.g., buy online, pick up in store; apply online, sign in person).
140
+
141
+ **Structure:** Journey map + explicit Channel row + Device row + Channel Transition markers at every handoff.
142
+
143
+ ### Related but NOT produced by this skill
144
+ - **Empathy Map** (Says/Thinks/Feels/Does quadrants) — attitudinal, not chronological. Use `/dp:research` synthesis instead.
145
+ - **User Flow Diagram** — screen-by-screen, UI-centric. Use `/dp:ux`.
146
+
147
+ ---
148
+
149
+ ## The Six-Step Process
150
+
151
+ The skill runs the user through these six steps. Each has a clear input and output.
152
+
153
+ ### Step 1 — Define scope
154
+ - Pick artifact type (from the four above)
155
+ - Confirm actor (persona): one persona per map
156
+ - Define scenario: specific, time-bounded, outcome-oriented
157
+ - State the actor's expectations entering the scenario
158
+ - Define phases: 4-7 high-level stages (Awareness → Consideration → Purchase → Onboarding → Usage → Advocacy is a common template; customize per domain)
159
+
160
+ **Anti-pattern:** scenarios like "uses our product" (too broad). Good: "renews an expiring subscription from a billing email."
161
+
162
+ ### Step 2 — Gather inputs
163
+ - Research artifacts: interviews, usability tests, support tickets, analytics
164
+ - Existing docs: personas, flow diagrams, SOPs
165
+ - Stakeholder knowledge: CS team, sales, ops
166
+ - If workflow mode with research: load automatically
167
+ - If no research: enter hypothesis mode and log the gap
168
+
169
+ ### Step 3 — Synthesize per phase
170
+ For each phase, fill in these swimlanes:
171
+
172
+ | Swimlane | Question it answers | Source |
173
+ |---|---|---|
174
+ | **Actions** | What does the actor do? | Observable behavior |
175
+ | **Thoughts / Mindset** | What are they thinking? | Interview quotes |
176
+ | **Emotions** | How do they feel? (1-5 scale or curve) | Observed + self-reported |
177
+ | **Touchpoints** | What interfaces/channels do they use? | Channel inventory |
178
+ | **Pain Points** | What's frustrating? | Research signals |
179
+ | **Opportunities** | Where could we improve? | Derived insight |
180
+ | **Internal Ownership** | Which team owns each part? | Org map |
181
+
182
+ For service blueprints, add:
183
+ | **Frontstage** | What does the employee/system do visibly? |
184
+ | **Backstage** | What happens behind the scenes? |
185
+ | **Support Processes** | What enables backstage actions? |
186
+
187
+ For omnichannel maps, mark every **Channel Transition** as a first-class event with:
188
+ - Source channel → destination channel
189
+ - What context carries over (or doesn't)
190
+ - Failure modes if context is lost
191
+
192
+ ### Step 4 — Draft the artifact
193
+ Produce the structured markdown output (see Output Structure below).
194
+
195
+ ### Step 5 — Validate with stakeholders (offline step)
196
+ The skill outputs a "Validation Checklist" section listing who should review each swimlane.
197
+
198
+ ### Step 6 — Identify next actions
199
+ - Top 3 opportunity zones (ranked by severity × reach × strategic fit)
200
+ - Suggested research to close [HYPOTHESIS] entries
201
+ - Handoff to UX phase
202
+
203
+ ---
204
+
205
+ ## Journey Map Anatomy
206
+
207
+ Every journey map this skill produces has these zones (NNGroup's Zone A/B/C model):
208
+
209
+ ```
210
+ ┌─────────────────────────────────────────────────────────────────┐
211
+ │ ZONE A — The Lens │
212
+ │ Actor + Scenario + Expectations │
213
+ ├─────────────────────────────────────────────────────────────────┤
214
+ │ ZONE B — The Experience │
215
+ │ ───────────────────────────────────────────────────────────── │
216
+ │ Phase 1 Phase 2 Phase 3 Phase 4 Phase 5 │
217
+ │ ───────────────────────────────────────────────────────────── │
218
+ │ Actions Actions Actions Actions Actions │
219
+ │ Thoughts Thoughts Thoughts Thoughts Thoughts │
220
+ │ Emotions ▁▂▅▇▅▃▁ (curve across all phases) │
221
+ │ Touchpoints Touchpoints Touchpoints Touchpoints Touchpoints │
222
+ ├─────────────────────────────────────────────────────────────────┤
223
+ │ ZONE C — The Insights │
224
+ │ Pain Points | Opportunities | Ownership | Metrics │
225
+ └─────────────────────────────────────────────────────────────────┘
226
+ ```
227
+
228
+ ---
229
+
230
+ ## Omnichannel Specifics
231
+
232
+ When artifact type is "Omnichannel Journey Map":
233
+
234
+ ### Apply NNGroup's 5 Components of Omnichannel UX (Kim Flaherty)
235
+ 1. **Consistent** — a cohesive, familiar experience across channels (brand, content, data, core functionality)
236
+ 2. **Optimized (for context)** — each channel's UI is suited to its device, constraints, and context of use (not a copy-paste of desktop)
237
+ 3. **Seamless** — channel transitions involve zero or minimal overhead; users can pick up where they left off
238
+ 4. **Orchestrated** — proactively guides customers through their journey with the right interaction at the right time
239
+ 5. **Collaborative** — lets customers use multiple channels *simultaneously* (e.g., agent call + web screen-share, TV + mobile companion app)
240
+
241
+ ### Define touchpoints precisely (NNGroup, Kim Salazar)
242
+ A **touchpoint** = **channel × device × task**. Separate these explicitly:
243
+ - **Channel** — method of communication/delivery (web, app, call center, store, email, SMS)
244
+ - **Device** — hardware (phone, laptop, kiosk, POS terminal)
245
+ - **Touchpoint** — a specific interaction = channel + device + task
246
+
247
+ A **touchpoint inventory** enumerates every (channel × device × task) combo the actor hits across the journey.
248
+
249
+ ### Treat channel transitions as first-class events
250
+ At every handoff, document:
251
+ - What the user just did (source channel)
252
+ - What they try to do next (destination channel)
253
+ - What context *should* carry over (auth, cart, preferences, session state, intent)
254
+ - What *actually* carries over (current reality)
255
+ - Failure mode if context is lost (forced re-login, re-typing, re-explaining)
256
+
257
+ ### Multichannel vs cross-channel vs omnichannel (precise NNGroup usage)
258
+ - **Multichannel** — presence on many channels, but each designed in isolation. No shared state, no transition design.
259
+ - **Cross-channel** — channels are coordinated (e.g., email contains a web link that persists session).
260
+ - **Omnichannel** — channels are designed as a connected system: each optimized for its context, transitions explicitly designed, built around the customer's journey rather than the org's channel silos.
261
+
262
+ **Consistent what, contextual how:** keep brand, data, and core capability consistent across channels; let UI, interaction modality, and detail level adapt to each channel's context.
263
+
264
+ Call out in the output which tier the current experience operates at.
265
+
266
+ ### Common omnichannel pitfalls to flag
267
+ - Treating multichannel presence as omnichannel
268
+ - Siloed ownership (each channel owned by a different team)
269
+ - Inconsistent data state across channels (stale cart, stale status)
270
+ - Forcing channel parity (replicating desktop UI on mobile)
271
+ - Unmanaged handoffs (re-auth, re-enter, re-explain)
272
+ - Over-personalization without permission
273
+ - Mapping only the happy path — gaps live at transitions and recovery paths
274
+ - Skipping the touchpoint inventory
275
+
276
+ ---
277
+
278
+ ## Service Blueprint Specifics
279
+
280
+ When artifact type is "Service Blueprint":
281
+
282
+ ### The five layers (top to bottom)
283
+ 1. **Physical Evidence** — tangible artifacts the customer encounters (receipt, signage, UI screen)
284
+ 2. **Customer Actions** — what the customer does (this IS the journey map row)
285
+ 3. **Frontstage Actions** — what employees/systems do visibly
286
+ 4. **Backstage Actions** — what employees/systems do invisibly
287
+ 5. **Support Processes** — upstream systems, policies, and vendors
288
+
289
+ ### The three lines
290
+ - **Line of Interaction** — between Customer Actions and Frontstage (every interaction crosses this)
291
+ - **Line of Visibility** — between Frontstage and Backstage (customer cannot see below this)
292
+ - **Line of Internal Interaction** — between Backstage and Support Processes
293
+
294
+ ### When to use vs journey map
295
+ Use a service blueprint when:
296
+ - Failures happen backstage but surface frontstage
297
+ - Cross-team coordination is the actual problem (not UI)
298
+ - You're designing a new service, not just a new interface
299
+
300
+ ---
301
+
302
+ ## Journey Mapping vs. Journey Management
303
+
304
+ A one-time map is an *artifact*. A managed journey is an *operating practice*. This skill produces the artifact but also equips the team for the practice.
305
+
306
+ **Journey management** (NNGroup, Sarah Gibbons): *"the ongoing practice of researching, measuring, optimizing, and orchestrating a customer journey to improve the customer experience for users and achieve business goals."*
307
+
308
+ ### The 3 competencies of journey management
309
+ 1. **Collecting insights** — continuous research into the journey (not once at kickoff)
310
+ 2. **Analyzing insights to drive design strategy** — turning observations into roadmap decisions
311
+ 3. **Orchestrating journey experiences for users** — delivering the right interaction at the right moment
312
+
313
+ ### What "managed" journeys have that one-off maps don't
314
+ - **A single named owner** (RACI "A") responsible for the journey end-to-end
315
+ - **A review cadence** (typically monthly/quarterly) — without this, the map drifts from reality within ~6 months
316
+ - **Metrics tied to the journey** across three tiers:
317
+ - *Experience KPIs*: NPS, CSAT, CES (Customer Effort Score)
318
+ - *Behavioral KPIs*: completion rate, drop-off rate, time-to-complete
319
+ - *Business KPIs*: revenue per user, retention, cost-to-serve
320
+ - **A validation plan** — research planned for the most-risky hypotheses
321
+ - **A connection to delivery** — insights feed concrete roadmap items with owners
322
+
323
+ The skill's output includes an **Ownership & Governance** section to seed these practices. Whether the team operationalizes it is organizational maturity — the skill flags when a project warrants managed-journey treatment (e.g., multi-team service, omnichannel, high customer-effort journey).
324
+
325
+ ---
326
+
327
+ ## Hypothesis Mode
328
+
329
+ When no research is available, the skill:
330
+
331
+ 1. Proceeds with map creation based on stakeholder input and domain knowledge
332
+ 2. Prefixes every Thoughts / Emotions / Pain Points entry with `[HYPOTHESIS]`
333
+ 3. Adds a **Validation Plan** section listing:
334
+ - 5-8 specific research questions to validate key claims
335
+ - Recommended method per question (interview / usability test / survey / diary study / analytics pull)
336
+ - Priority order (highest-risk hypotheses first)
337
+ 4. Adds a banner to the output: `⚠ HYPOTHESIS-BASED — Not validated with research`
338
+
339
+ This honors the "Research-based" principle while letting teams move forward when research isn't yet available.
340
+
341
+ ---
342
+
343
+ ## Output Structure (Workflow Mode)
344
+
345
+ When in workflow mode, write to `.design/phases/JOURNEY-MAP.md`:
346
+
347
+ ```yaml
348
+ ---
349
+ phase: journey
350
+ skill: dp-journey
351
+ artifact_type: [customer_journey | experience_map | service_blueprint | omnichannel_journey]
352
+ completed: YYYY-MM-DDTHH:MM:SSZ
353
+ mode: [research_based | hypothesis]
354
+ actor: [persona name]
355
+ scenario: [one-line scenario]
356
+ phases_count: N
357
+ research_sources:
358
+ - RESEARCH-interviews.md
359
+ - RESEARCH-usability.md
360
+ validation_status: [validated | partial | unvalidated]
361
+ ---
362
+
363
+ # Journey Map: [Scenario title]
364
+
365
+ > Artifact type: [Customer Journey Map | Experience Map | Service Blueprint | Omnichannel Journey Map]
366
+ > Mode: [Research-based | Hypothesis-based ⚠]
367
+
368
+ ## Zone A — The Lens
369
+
370
+ **Actor:** [Persona name + one-line description]
371
+
372
+ **Scenario:** [Specific, time-bounded, outcome-oriented scenario]
373
+
374
+ **Actor's Expectations Entering:**
375
+ - [Expectation 1]
376
+ - [Expectation 2]
377
+ - [Expectation 3]
378
+
379
+ **Actor's Goal:** [What success looks like from their perspective]
380
+
381
+ ## Zone B — The Experience
382
+
383
+ ### Phases
384
+ | # | Phase Name | Duration | Key Question |
385
+ |---|---|---|---|
386
+ | 1 | [Phase 1] | [e.g., minutes / days] | [What is the actor trying to achieve?] |
387
+ | ... | ... | ... | ... |
388
+
389
+ ### Phase-by-Phase Breakdown
390
+
391
+ #### Phase 1: [Phase Name]
392
+
393
+ **Actions**
394
+ - [What the actor does]
395
+ - [Next action]
396
+
397
+ **Thoughts**
398
+ - [Verbatim or paraphrased quotes — "..." if from research]
399
+
400
+ **Emotions** — [value on 1-5 scale, e.g., 3/5 neutral]
401
+ [Short description of emotional state]
402
+
403
+ **Touchpoints / Channels**
404
+ - [Touchpoint 1] ([channel type])
405
+ - [Touchpoint 2] ([channel type])
406
+
407
+ **Pain Points**
408
+ - [Pain point 1 — with research source or [HYPOTHESIS] flag]
409
+
410
+ **Opportunities**
411
+ - [Opportunity 1 — concrete, actionable]
412
+
413
+ **Internal Ownership**
414
+ - [Team / role responsible]
415
+
416
+ [Repeat for each phase]
417
+
418
+ ### Emotion Curve (across all phases)
419
+ ```
420
+ 5 ┤
421
+ 4 ┤ ╱╲
422
+ 3 ┤ ╱ ╲___
423
+ 2 ┤ ╱ ╲
424
+ 1 ┤_╱ ╲___
425
+ └────────────────
426
+ P1 P2 P3 P4 P5
427
+ ```
428
+
429
+ ## Zone C — The Insights
430
+
431
+ ### Top 3 Opportunity Zones
432
+ Ranked by severity × reach × strategic fit:
433
+
434
+ 1. **[Opportunity name]** — [Phase X]
435
+ - Severity: [1-5] — [why]
436
+ - Reach: [% of users affected]
437
+ - Strategic fit: [alignment with org goals]
438
+ - Suggested action: [concrete next step]
439
+
440
+ 2. ...
441
+
442
+ 3. ...
443
+
444
+ ### Key Moments of Truth
445
+ Critical interactions where the experience succeeds or fails:
446
+ - [Moment 1] — [why it matters]
447
+ - [Moment 2] — [why it matters]
448
+
449
+ ### Ownership & Governance
450
+ **Journey Owner (accountable):** [Name / Role — single person, RACI "A"]
451
+
452
+ **Review Cadence:** [Weekly | Monthly | Quarterly] — [rationale]
453
+
454
+ **Metrics to Monitor**
455
+ | Tier | Metric | Current | Target | Source |
456
+ |---|---|---|---|---|
457
+ | Experience | NPS / CSAT / CES | [value] | [target] | [survey tool] |
458
+ | Behavioral | Completion rate | [%] | [%] | [analytics] |
459
+ | Behavioral | Drop-off points | [phase X] | — | [analytics] |
460
+ | Business | Revenue / retention / cost-to-serve | [value] | [target] | [system] |
461
+
462
+ **Phase Ownership**
463
+ | Phase | Primary Owner | Secondary | Handoff Risks |
464
+ |---|---|---|---|
465
+ | Phase 1 | [Team] | [Team] | [What breaks at handoff] |
466
+
467
+ ## [If Service Blueprint] Backstage Analysis
468
+
469
+ ### Frontstage Actions
470
+ [Per phase — what employees/systems do visibly]
471
+
472
+ ### Backstage Actions
473
+ [Per phase — what happens behind the line of visibility]
474
+
475
+ ### Support Processes
476
+ [Upstream systems, policies, vendors that enable backstage]
477
+
478
+ ### Cross-Line Failure Risks
479
+ | Failure | Where | Customer Impact |
480
+ |---|---|---|
481
+ | [e.g., CRM sync delay] | Backstage → Frontstage | Agent sees stale data |
482
+
483
+ ## [If Omnichannel] Channel Transition Analysis
484
+
485
+ ### Channels in This Journey
486
+ | Channel | Role | Strengths Leveraged |
487
+ |---|---|---|
488
+ | [Channel 1] | [Primary / secondary / fallback] | [What it does best] |
489
+
490
+ ### Channel Transitions
491
+ | # | From | To | Context That Should Carry | Context That Does | Failure Mode |
492
+ |---|---|---|---|---|---|
493
+ | 1 | [Email] | [Web] | [Auth, offer ID] | [Offer ID only] | [Forces re-login] |
494
+
495
+ ### Omnichannel Tier
496
+ Current state: [Multichannel | Cross-channel | Omnichannel]
497
+ [One-line justification]
498
+
499
+ ## [If Hypothesis Mode] Validation Plan
500
+
501
+ ⚠ This map is hypothesis-based. Validate before making large investments.
502
+
503
+ ### Highest-Risk Hypotheses
504
+ 1. **Claim:** [Hypothesis from the map]
505
+ **Why risky:** [What decisions depend on it]
506
+ **Method:** [Interview / usability test / survey / analytics]
507
+ **Sample:** [N, criteria]
508
+ **Timing:** [Before what decision]
509
+
510
+ [Repeat for top 5-8 hypotheses]
511
+
512
+ ## Handoff Notes for UX Phase
513
+
514
+ - Key opportunities to design for: [list]
515
+ - Phases needing the most UX attention: [list]
516
+ - Cross-channel requirements: [if applicable]
517
+ - Open questions for UX: [list]
518
+ ```
519
+
520
+ ---
521
+
522
+ ## State Updates (Workflow Mode)
523
+
524
+ After completing the journey map:
525
+
526
+ 1. **Write output to `.design/phases/JOURNEY-MAP.md`**
527
+
528
+ 2. **Update `.design/STATE.md`:**
529
+ ```markdown
530
+ ### Last Activity
531
+ - **Date:** [TIMESTAMP]
532
+ - **Action:** Completed journey mapping with /dp:journey
533
+ - **Artifact type:** [type]
534
+ - **Mode:** [research-based | hypothesis]
535
+
536
+ #### Major Decisions Made
537
+ | Phase | Decision | Impact |
538
+ |---|---|---|
539
+ | Journey | [Top opportunity identified] | [Feeds UX priority] |
540
+ ```
541
+
542
+ 3. **Update `.design/config.json`:**
543
+ ```json
544
+ {
545
+ "optional_phases": {
546
+ "journey": {
547
+ "enabled": true,
548
+ "artifact_type": "customer_journey",
549
+ "mode": "research_based",
550
+ "completed": true
551
+ }
552
+ },
553
+ "workflow": {
554
+ "phases_completed": [..., "journey"],
555
+ "current_optional_phase": null
556
+ }
557
+ }
558
+ ```
559
+
560
+ **State-machine rules for this optional phase:**
561
+ - **On entry** (as soon as the user invokes `/dp:journey`): set `workflow.current_optional_phase` to `"journey"` (if it isn't already). This lets `/dp:progress` and `/dp:skip` know the user is currently inside a subphase.
562
+ - **On completion** (after writing JOURNEY-MAP.md): clear `workflow.current_optional_phase` to `null` so the main workflow is no longer marked as in-flight on a subphase. Do **not** change `workflow.current_phase` — the numeric main-phase value is governed by the main workflow skills (`/dp:discovery`, `/dp:ux`, etc.), not by optional subphases.
563
+
564
+ 4. **If any [HYPOTHESIS] entries exist, update `.design/REQUIREMENTS.md`** with a "Validation Needed" section.
565
+
566
+ ---
567
+
568
+ ## Handoff (Workflow Mode)
569
+
570
+ ```
571
+ ═══════════════════════════════════════════════════════════════════════════════
572
+ JOURNEY MAP COMPLETE
573
+ ═══════════════════════════════════════════════════════════════════════════════
574
+
575
+ Output: .design/phases/JOURNEY-MAP.md
576
+
577
+ Summary:
578
+ • Artifact: [type]
579
+ • Mode: [research-based | hypothesis ⚠]
580
+ • Phases mapped: [N]
581
+ • Top opportunities: [count]
582
+ • Validation needed: [count of hypotheses]
583
+
584
+ Ready for Next Phase?
585
+ ────────────────────────────────────────────────────────────────────────────────
586
+ → /dp:ux — Continue to UX phase (recommended)
587
+ → /dp:research — Validate hypotheses first (if hypothesis mode)
588
+ → /dp:prd — Generate PRD incorporating journey insights
589
+
590
+ Or:
591
+ → /dp:progress — Review full status
592
+ → /dp:back — Revisit discovery
593
+ ═══════════════════════════════════════════════════════════════════════════════
594
+ ```
595
+
596
+ ---
597
+
598
+ ## Standalone Mode Behavior
599
+
600
+ When no `.design/` directory exists:
601
+
602
+ 1. Ask artifact type (4 options)
603
+ 2. Ask actor + scenario
604
+ 3. Ask for research inputs (or enter hypothesis mode)
605
+ 4. Run the six-step process
606
+ 5. Output inline (rendered markdown)
607
+ 6. Offer: "Would you like to start a full DP workflow with `/dp:start`?"
608
+
609
+ ---
610
+
611
+ ## Common Pitfalls to Avoid (Kate Kaplan, NNGroup)
612
+
613
+ The skill actively guards against these ten:
614
+
615
+ 1. **No clear purpose or business question** — map has no owner, drives no decision, ends up as wall art
616
+ 2. **Basing the map on assumptions, not research** — "feelings" made up in a workshop rather than grounded in user data
617
+ 3. **Designing for the visual first** — over-polishing the artifact before synthesis is complete
618
+ 4. **Mixing actors in one map** — one map = one actor = one scenario; multi-actor maps dilute insight
619
+ 5. **Scoping too broadly** — "uses the product" or "the whole customer lifecycle" hides specifics; scope to one scenario
620
+ 6. **Leaving emotion out** — omitting the emotion curve reduces the map to a flowchart and kills empathy value
621
+ 7. **Not including stakeholders in creation** — presenting a finished map produces no buy-in; co-creation does
622
+ 8. **Treating it as one-and-done** — not updating the map as research/product evolves; dies on a wiki
623
+ 9. **Confusing journey map with service blueprint or flow chart** — conflating user experience with internal process
624
+ 10. **No opportunities or ownership** — stopping at "here's the problem" without who-owns-what and how-we-measure makes the map inactionable
625
+
626
+ ---
627
+
628
+ ## Reference Files
629
+
630
+ Load these as needed for detailed guidance:
631
+
632
+ - **references/journey-types.md** — Decision tree for picking artifact type; examples of each
633
+ - **references/map-structures.md** — Full templates for each of the four artifact types
634
+ - **references/research-methods.md** — How to gather inputs for each swimlane (actions, thoughts, emotions, pain points)
635
+ - **references/omnichannel-patterns.md** — Channel transition design, the 3 Cs, common cross-channel patterns
636
+
637
+ ---
638
+
639
+ ## Config Integration
640
+
641
+ Respects these settings from `.design/config.json`:
642
+
643
+ ```json
644
+ {
645
+ "optional_phases": {
646
+ "journey": {
647
+ "enabled": true,
648
+ "artifact_type": "customer_journey",
649
+ "mode": "research_based",
650
+ "include_ownership": true,
651
+ "include_emotion_curve": true
652
+ }
653
+ }
654
+ }
655
+ ```
656
+
657
+ - `artifact_type`: one of `customer_journey`, `experience_map`, `service_blueprint`, `omnichannel_journey`
658
+ - `mode`: `research_based` requires research sources; `hypothesis` allows proceeding without
659
+ - `include_ownership`: when true, require Internal Ownership per phase
660
+ - `include_emotion_curve`: when true, include the ASCII emotion curve
661
+
662
+ ---
663
+
664
+ ## Workflow Navigation
665
+
666
+ ```
667
+ ┌─────────┐
668
+ /dp:start → /dp:discovery → (/dp:prd) → │ YOU ARE │ → /dp:ux → /dp:execute → /dp:ui → /dp:eng_review → /dp:verify
669
+ Phase 1 Phase 1.5a │ HERE │ Phase 2
670
+ │ 1.5b │
671
+ └─────────┘
672
+ ```
673
+
674
+ | | |
675
+ |---|---|
676
+ | **Previous** | `/dp:discovery` — Discovery (Phase 1) |
677
+ | **Parallel** | `/dp:prd` — PRD generation (Phase 1.5a) |
678
+ | **Current** | `/dp:journey` — Journey mapping (Phase 1.5b) |
679
+ | **Next** | `/dp:ux` — UX principles & states (Phase 2) |
680
+ | **Related** | `/dp:research` — Run research to validate hypotheses |
681
+ | | `/dp:discuss` — Capture context before this phase |
682
+ | | `/dp:back` — Return to discovery if scope changes |