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,645 @@
1
+ ---
2
+ name: dp-storytell
3
+ description: >
4
+ Transform design work into compelling stories for stakeholders, executives, engineering, and
5
+ customers. Based on NNGroup storytelling methodology (Rachel Krause), Nancy Duarte, Minto Pyramid,
6
+ and Heath brothers' SUCCESs. Trigger for "/dp:storytell", design presentation, stakeholder
7
+ review, exec update, research readout, design critique prep, pitch deck, demo script, design
8
+ narrative, storytelling for UX. Cross-phase skill — invoke after any DP phase to produce
9
+ a ready-to-deliver presentation outline with structure, speaker notes, and audience-specific
10
+ framing.
11
+ ---
12
+
13
+ # Storytelling for Design Work
14
+
15
+ Great design loses to mediocre design that's better told. This skill packages the output of any DP phase into a deliberately structured narrative for a specific audience — so the design actually lands, gets approved, and drives action.
16
+
17
+ > **NNGroup framing (Krause):** A design story doesn't describe what you built. It dramatizes why it mattered, what happened, and what we do next.
18
+
19
+ ---
20
+
21
+ ## When to Use This Skill
22
+
23
+ Run `/dp:storytell` when you need to:
24
+
25
+ - **Pitch new design work** to leadership (get approval / budget)
26
+ - **Review a design** with cross-functional stakeholders
27
+ - **Present research findings** to a broad audience
28
+ - **Demo a prototype** to customers, execs, or internal users
29
+ - **Write an executive one-pager** summarizing a design decision
30
+ - **Prepare for a design critique** (your own or someone else's)
31
+ - **Run a postmortem** on a shipped design
32
+ - **Respond to skepticism** about a design direction
33
+
34
+ **Don't use this skill for:**
35
+ - Writing requirements → `/dp:prd`
36
+ - Building a journey map → `/dp:journey`
37
+ - Making design decisions → `/dp:ux`, `/dp:ui`
38
+ - Sprint-level updates (too tactical for narrative structure)
39
+
40
+ ---
41
+
42
+ ## DP Workflow Integration
43
+
44
+ This is a **cross-phase skill** — it does not sit at a specific workflow position. It can be invoked:
45
+
46
+ - After any DP phase to communicate the output
47
+ - At end of workflow as a capstone (`/dp:verify` → `/dp:storytell`)
48
+ - Standalone, not tied to a DP workflow
49
+
50
+ ### Detecting Workflow Mode
51
+
52
+ At the start of any `/dp:storytell` invocation:
53
+
54
+ 1. **Check for `.design/config.json`**
55
+ 2. **If found** (workflow mode):
56
+ - Load `.design/config.json`
57
+ - Ask: "Which phase output are we telling the story of?"
58
+ - Let the user pick: Discovery / PRD / Journey / Roadmap / Research / UX / UI / Review / Full workflow
59
+ - Load the relevant `.design/phases/*.md` file(s)
60
+ - **Check for storytelling-specific context:** if the user ran `/dp:discuss` before this skill, load any `.design/phases/STORYTELL-*-CONTEXT.md` files that exist. Use them to pre-fill the audience, framework, and framing questions below.
61
+ - Proceed to audience + format selection
62
+ 3. **If not found** (standalone mode):
63
+ - Ask the user to describe or paste the content to be told as a story
64
+ - Proceed to audience + format selection
65
+
66
+ ### Output (Workflow Mode)
67
+
68
+ Writes to `.design/phases/PRESENTATION-[topic].md` — one file per audience+format combination, so multiple presentations can coexist for the same content.
69
+
70
+ ---
71
+
72
+ ## Three Core Principles
73
+
74
+ Every presentation this skill produces is built on three principles, drawn from Nancy Duarte, Barbara Minto, and Tom Greever.
75
+
76
+ ### Principle 1 — Conflict is the engine (Duarte)
77
+ No conflict, no story. Nancy Duarte's **Sparkline** frames every great talk as oscillation between **"What Is"** (current state) and **"What Could Be"** (aspirational future), ending on **"New Bliss"** (the state *if the audience acts*).
78
+
79
+ Every presentation must contain:
80
+ - A clear **protagonist** — the user, or the team (not the company)
81
+ - A clear **antagonist** — the current painful state, the constraint, the risk
82
+ - A clear **resolution** — what we're proposing and why it works
83
+
84
+ The audience is the hero. You are the mentor (Yoda, not Luke).
85
+
86
+ Include somewhere in the middle a **STAR moment** ("Something They'll Always Remember") — a repeatable sound bite, a shocking stat, an evocative image, or a dramatic demo.
87
+
88
+ ### Principle 2 — Answer first (Minto)
89
+ Per Minto Pyramid Principle: lead with your conclusion, then support it. Executives don't want a mystery novel — they want the verdict in sentence one, then the evidence.
90
+
91
+ Minto's **SCQA intro structure:**
92
+ - **Situation** — the stable context everyone agrees on
93
+ - **Complication** — what changed or what's at risk
94
+ - **Question** — the question the complication raises
95
+ - **Answer** — your recommendation (the governing thought)
96
+
97
+ Below the governing thought, group supporting ideas **MECE** (mutually exclusive, collectively exhaustive). Each level answers "why?" or "how?" from the level above.
98
+
99
+ **Answer-first for execs, process-second for peers.**
100
+
101
+ ### Principle 3 — The response loop (Greever)
102
+ When feedback comes — especially critical feedback — don't defend. Use Tom Greever's 3-step process from *Articulating Design Decisions*:
103
+
104
+ 1. **Listen** — let them finish. Take notes. Don't interrupt even if they're wrong.
105
+ 2. **Understand** — restate their concern in your words: *"So what I'm hearing is you're worried that X will cause Y. Is that right?"* Confirms, refines vague concerns, buys thinking time.
106
+ 3. **Respond** — tie your answer to (a) the project goal, (b) the user, and (c) a prior agreement or data point.
107
+
108
+ This loop appears in the Q&A prep and delivery notes of every output.
109
+
110
+ ---
111
+
112
+ ## Audience Framework
113
+
114
+ Every story is built for a specific audience. Pick one at the start.
115
+
116
+ ### The 5 Primary Audiences
117
+
118
+ | Audience | Primary concern | Time budget | Preferred format |
119
+ |---|---|---|---|
120
+ | **Executive / leadership** | Business outcome, risk, resources | 5-10 min | Answer-first, 1-pager, BLUF |
121
+ | **Peer designer / design review** | Craft quality, alternatives considered, rationale | 30-60 min | Process-narrative, critique-ready |
122
+ | **Engineering** | Feasibility, constraints, edge cases, handoff quality | 20-45 min | Spec-backed, state-rich |
123
+ | **Product management** | Metrics, tradeoffs, scope, sequencing | 20-40 min | Theme-based, outcome-tied |
124
+ | **Customer / end user** | Benefit to me, no jargon, visible value | 5-15 min | Demo, before/after, testimonial |
125
+
126
+ ### Audience diagnostic questions (skill asks these)
127
+
128
+ Before writing the story, the skill asks:
129
+ 1. Who is the primary audience? (pick one from above — if multiple, prioritize)
130
+ 2. What decision do they need to make?
131
+ 3. What's their starting position? (supportive / neutral / skeptical / hostile)
132
+ 4. How much time do they have?
133
+ 5. What's the delivery mode? (live presentation / deck to read / memo / demo)
134
+ 6. What's the worst-case objection?
135
+
136
+ These answers govern every downstream choice.
137
+
138
+ ---
139
+
140
+ ## Narrative Frameworks
141
+
142
+ The skill selects a narrative framework based on the story's purpose. See `references/narrative-frameworks.md` for full details on each.
143
+
144
+ ### Quick selector
145
+
146
+ | Purpose | Framework |
147
+ |---|---|
148
+ | Pitch new work to exec | **SCR** (Situation → Complication → Resolution) + Minto |
149
+ | Research findings readout | **Before / During / After** or **Problem-Insight-Recommendation** |
150
+ | Design proposal | **NABC** (Need, Approach, Benefits per Cost, Competition) |
151
+ | Pivot / strategic shift | **3-Act Structure** (setup, confrontation, resolution) |
152
+ | Case study / retro | **STAR** (Situation, Task, Action, Result) |
153
+ | Journey / change story | **Pixar Story Spine** or **Hero's Journey** |
154
+ | Complex explanation for a lay audience | **Pyramid Principle** (Minto) |
155
+ | Highly emotional / cultural shift | **Freytag's Pyramid** (exposition → rising action → climax → resolution) |
156
+
157
+ ### The Heath brothers' SUCCESs (message stickiness)
158
+ Every story the skill produces is tested against these 6 criteria:
159
+ - **Simple** — one core idea, ruthlessly curated
160
+ - **Unexpected** — breaks a pattern; surprises the audience
161
+ - **Concrete** — specific, not abstract (named users, real quotes, actual screens)
162
+ - **Credible** — backed by research, data, or demonstrated via prototype
163
+ - **Emotional** — makes the audience feel something (frustration for users, urgency for the team)
164
+ - **Story** — has a narrative arc, not a bullet list
165
+
166
+ ---
167
+
168
+ ## Content-Type Templates
169
+
170
+ The skill supports six distinct content types. Pick one based on the goal.
171
+
172
+ ### Type 1 — Design Proposal (pitching new work)
173
+ **Goal:** get approval / budget / resources
174
+ **Default framework:** SCR + NABC
175
+ **Structure:**
176
+ 1. **Hook** (10%) — one sentence + one user quote or data point
177
+ 2. **Situation** (15%) — where we are today
178
+ 3. **Complication** (25%) — why current state is painful; evidence
179
+ 4. **Resolution** (40%) — what we propose; how it works; why it works
180
+ 5. **Ask** (10%) — specific decision / resources needed
181
+
182
+ ### Type 2 — Design Review (showing work for critique)
183
+ **Goal:** get usable feedback; align peers
184
+ **Default framework:** Process narrative (for peers) or Problem-Solution (for PMs)
185
+ **Structure:**
186
+ 1. **Context** (15%) — constraint/goal recap
187
+ 2. **Exploration** (30%) — alternatives considered, what was rejected and why
188
+ 3. **Current direction** (35%) — the design + rationale
189
+ 4. **Open questions** (10%) — specific items for feedback
190
+ 5. **Next steps** (10%) — what happens after this review
191
+
192
+ ### Type 3 — Research Readout (presenting findings)
193
+ **Goal:** share insights; drive decisions
194
+ **Default framework:** Problem-Insight-Recommendation per finding
195
+ **Structure:**
196
+ 1. **Method snapshot** (10%) — who, how many, how
197
+ 2. **Top-line findings** (20%) — 3-5 headlines, each with one data point
198
+ 3. **Deep dives** (40%) — for each finding: evidence (quote/video), pattern, implication
199
+ 4. **Recommendations** (20%) — concrete actions, prioritized
200
+ 5. **Next research** (10%) — open questions
201
+
202
+ ### Type 4 — Executive One-Pager
203
+ **Goal:** busy leader makes a decision without a meeting
204
+ **Default framework:** BLUF + Minto Pyramid
205
+ **Structure:**
206
+ ```
207
+ ╔══════════════════════════════════════════════════════════════╗
208
+ ║ [ONE-LINE CONCLUSION] ║
209
+ ╠══════════════════════════════════════════════════════════════╣
210
+ ║ Why this matters: [1 sentence] ║
211
+ ║ ║
212
+ ║ What we're proposing: [2-3 bullets] ║
213
+ ║ ║
214
+ ║ Evidence: [3 data points or 1 user quote] ║
215
+ ║ ║
216
+ ║ Decision needed: [specific ask + deadline] ║
217
+ ║ ║
218
+ ║ Risk if we don't act: [1 sentence] ║
219
+ ╠══════════════════════════════════════════════════════════════╣
220
+ ║ Owner: [Name] · Deadline: [Date] ║
221
+ ╚══════════════════════════════════════════════════════════════╝
222
+ ```
223
+
224
+ ### Type 5 — Prototype / Demo Walkthrough
225
+ **Goal:** audience experiences the design
226
+ **Default framework:** Journey-based (walk the user's path)
227
+ **Structure:**
228
+ 1. **Set the scene** (10%) — "Imagine you're [persona], trying to [scenario]"
229
+ 2. **Walk the path** (70%) — demonstrate step by step, in user voice
230
+ 3. **Zoom-out moments** (15%) — pause to highlight decision rationale
231
+ 4. **Unanswered scenarios** (5%) — edge cases not yet designed
232
+
233
+ ### Type 6 — Postmortem / Retrospective
234
+ **Goal:** learn from what happened
235
+ **Default framework:** STAR or 3-Act
236
+ **Structure:**
237
+ 1. **What we set out to do** (15%) — original goal + hypotheses
238
+ 2. **What happened** (35%) — facts, timeline, metrics
239
+ 3. **What we learned** (35%) — insights, surprises, errors
240
+ 4. **What changes** (15%) — concrete adjustments for next time
241
+
242
+ ---
243
+
244
+ ## Design-Specific Story Patterns
245
+
246
+ Beyond formal frameworks, these are patterns that work specifically for design work.
247
+
248
+ ### Pattern A — User quote opener
249
+ Start with a verbatim user statement. Creates immediate empathy and credibility.
250
+ > *"I've been trying to do this for 20 minutes and I just gave up."* — Sarah, P4
251
+
252
+ ### Pattern B — Before / After side-by-side
253
+ Two screens. Current state left, proposed right. Minimal annotation. The contrast speaks.
254
+
255
+ ### Pattern C — Data-insight-action
256
+ Number → what it means → what we do about it.
257
+ > *"40% of users abandon at step 3. That's the step we introduce unasked-for configuration. We propose removing it."*
258
+
259
+ ### Pattern D — Journey-emotion curve
260
+ Plot the emotion line across phases. Point to valleys. Show the fix narrows or closes the valley.
261
+
262
+ ### Pattern E — Counterfactual
263
+ "If we don't do this, here's what happens." Used sparingly — too often and it reads as fear-mongering.
264
+
265
+ ### Pattern F — Small-bet demo
266
+ Show a cheap prototype or scrappy test that validates the direction. Reduces risk perception.
267
+
268
+ ### Pattern G — Expert-voice sandwich
269
+ Your opinion, supported by an authoritative source (Nielsen heuristic, research paper, competitor benchmark), then back to your specific case.
270
+
271
+ ---
272
+
273
+ ## Stakeholder Dynamics
274
+
275
+ Real presentations have difficult moments. The skill prepares users for these.
276
+
277
+ ### Handling skeptics
278
+ **Sign:** stakeholder repeatedly interrupts with "but what about..."
279
+ **Tactic:** thank them, write the question on a parking lot, continue. Address in Q&A with "you asked about X — here's what we considered."
280
+
281
+ ### Handling "I don't like blue" feedback
282
+ **Sign:** aesthetic opinion posed as professional critique
283
+ **Tactic:** acknowledge the reaction, redirect to decision criteria: "What are we trying to make the user feel here?" Translate subjective to objective.
284
+
285
+ ### Handling scope-expansion attacks
286
+ **Sign:** "Could we also add X, Y, Z?"
287
+ **Tactic:** yes-and: "Great thought — that's on our Future roadmap. For this cycle we're focused on [scope] because [reason]."
288
+
289
+ ### Handling the silent room
290
+ **Sign:** no one reacts after you present
291
+ **Tactic:** ask a specific person a specific question. Not "any thoughts?" but "Priya, from engineering's perspective, what's the riskiest part of this?"
292
+
293
+ ### Handling leadership override
294
+ **Sign:** exec says "just do X" mid-presentation, overriding your proposal
295
+ **Tactic:** don't debate in the room. "Happy to explore that — can I take 24 hours to assess the tradeoff and come back?" Buys time to respond with evidence.
296
+
297
+ ### Handling "design by committee"
298
+ **Sign:** every stakeholder wants a tweak, none are individually critical
299
+ **Tactic:** enumerate all requests, then force prioritization: "We can do 3 of these before deadline. Which 3?"
300
+
301
+ ---
302
+
303
+ ## Visual Storytelling Principles
304
+
305
+ Slides and prototypes are part of the story. The skill enforces these principles.
306
+
307
+ ### Slide design
308
+ - **One idea per slide** — if there are 2, split them
309
+ - **Image > bullet list** — show the actual design, not a description of it
310
+ - **Text as signposts** — titles do the narrative work, not body copy
311
+ - **Data in service of a point** — chart titles state the insight, not the axis
312
+ - **Dark deck for demos, light deck for reading** — contrast with delivery context
313
+
314
+ ### Prototypes vs static screens
315
+ - **Static screens** — when the critique is about the design itself (layout, hierarchy, visual)
316
+ - **Clickable prototype** — when the critique is about the flow, interaction, or feel
317
+ - **Video walkthrough** — when time is short, or you need to guarantee consistent delivery
318
+ - **Live product** — only when it's stable and you want to build trust through authenticity
319
+
320
+ ### Video clip best practices (for research readouts)
321
+ - **15-45 seconds** per clip
322
+ - **Set context** before playing ("This is P5, trying to complete signup for the second time.")
323
+ - **Never play more than 3 clips in a row** — audience attention collapses
324
+ - **Transcribe the clip below it** — so reading viewers (and post-meeting skimmers) still get the content
325
+
326
+ ---
327
+
328
+ ## Output Structure (Workflow Mode)
329
+
330
+ Writes to `.design/phases/PRESENTATION-[topic].md`:
331
+
332
+ ```yaml
333
+ ---
334
+ phase: storytell
335
+ skill: dp-storytell
336
+ content_type: [design_proposal | design_review | research_readout | exec_one_pager | demo_walkthrough | postmortem]
337
+ source_phases: [discovery | prd | journey | roadmap | research | ux | ui | review]
338
+ audience: [executive | peer | engineering | product | customer]
339
+ framework_used: [SCR | NABC | Minto | STAR | 3-Act | Pixar Spine | Problem-Insight-Recommendation]
340
+ delivery_mode: [live_presentation | deck_to_read | memo | demo]
341
+ duration: [5min | 15min | 30min | 60min]
342
+ completed: YYYY-MM-DDTHH:MM:SSZ
343
+ ---
344
+
345
+ # Presentation: [Topic]
346
+
347
+ > Audience: [primary audience]
348
+ > Framework: [chosen framework]
349
+ > Duration: [target]
350
+ > Delivery: [mode]
351
+
352
+ ## Opening Hook
353
+
354
+ **Hook type:** [user quote | data point | provocative question | before/after]
355
+
356
+ **Opening line (speak first):**
357
+ > "[Exact opening sentence]"
358
+
359
+ **Visual (show first):**
360
+ [Description of first slide / screen / image]
361
+
362
+ ---
363
+
364
+ ## Narrative Arc (beat-by-beat)
365
+
366
+ ### Beat 1 — [Name] ([time allocation])
367
+ **Goal:** [what this beat accomplishes]
368
+ **Content:**
369
+ - [Point 1]
370
+ - [Point 2]
371
+
372
+ **Speaker notes:**
373
+ > "[What to say verbatim]"
374
+
375
+ **Visual:**
376
+ [What to show]
377
+
378
+ **Transition to next beat:**
379
+ > "[Transition sentence]"
380
+
381
+ [Repeat for each beat]
382
+
383
+ ---
384
+
385
+ ## Evidence Package
386
+
387
+ **Data points** (max 3 headline numbers):
388
+ 1. [Number] — [what it means] — [source]
389
+ 2. ...
390
+
391
+ **User quotes** (max 3, 1-2 sentences each):
392
+ 1. *"[Quote]"* — [User identifier], [context]
393
+ 2. ...
394
+
395
+ **Visuals** (in order of appearance):
396
+ 1. [Current state screen / painful path]
397
+ 2. [Proposed state screen / improved path]
398
+ 3. [Data visualization]
399
+
400
+ ---
401
+
402
+ ## The Ask
403
+
404
+ **Primary ask (one sentence):**
405
+ > "[What you need from the audience]"
406
+
407
+ **Decision criteria** (how they'll evaluate):
408
+ - [Criterion 1]
409
+ - [Criterion 2]
410
+
411
+ **Timeline:**
412
+ - Decision needed by: [date]
413
+ - Execution starts: [date]
414
+
415
+ ---
416
+
417
+ ## Q&A Preparation
418
+
419
+ **Top 5 anticipated questions:**
420
+ 1. **Q:** [Likely question]
421
+ **A:** [Crisp answer, 1-3 sentences]
422
+ 2. ...
423
+
424
+ **Hostile questions & redirects:**
425
+ - If asked "[X]" → respond with "[Y]"
426
+
427
+ **What to do if asked something you don't know:**
428
+ > "Great question — I want to give you a data-backed answer. Let me come back within 24 hours with specifics."
429
+
430
+ ---
431
+
432
+ ## Delivery Notes
433
+
434
+ - **Pacing:** [where to slow down, where to speed up]
435
+ - **Silences:** [where to pause intentionally]
436
+ - **Physical:** [in-person only — stand/sit, hands, movement]
437
+ - **Voice:** [emphasis points, tone shifts]
438
+
439
+ ---
440
+
441
+ ## Slide-by-Slide Outline
442
+
443
+ (If the format is a deck.)
444
+
445
+ | # | Slide title | Visual | Speaker beat |
446
+ |---|---|---|---|
447
+ | 1 | [Title or hook] | [Image] | [Beat 1 opening] |
448
+ | 2 | ... | ... | ... |
449
+
450
+ ---
451
+
452
+ ## SUCCESs Self-Check
453
+
454
+ - [ ] **Simple** — core idea in one sentence?
455
+ - [ ] **Unexpected** — does it break a pattern?
456
+ - [ ] **Concrete** — specific users, real quotes, actual screens?
457
+ - [ ] **Credible** — research, data, or prototype backing?
458
+ - [ ] **Emotional** — will the audience feel something?
459
+ - [ ] **Story** — clear arc with conflict and resolution?
460
+
461
+ ---
462
+
463
+ ## Post-Presentation Follow-Up Plan
464
+
465
+ - **Send-after artifact:** [1-pager / recording / deck]
466
+ - **Decision capture:** [what was decided / deferred / rejected]
467
+ - **Follow-up owners:** [who does what next]
468
+ - **Success measure:** [what tells us the presentation worked]
469
+ ```
470
+
471
+ ---
472
+
473
+ ## State Updates (Workflow Mode)
474
+
475
+ After completing the presentation:
476
+
477
+ 1. **Write output to `.design/phases/PRESENTATION-[topic].md`**
478
+
479
+ 2. **Update `.design/STATE.md`:**
480
+ ```markdown
481
+ ### Last Activity
482
+ - **Date:** [TIMESTAMP]
483
+ - **Action:** Built presentation for [audience] with /dp:storytell
484
+ - **Content type:** [type]
485
+ - **Source phase:** [phase]
486
+ ```
487
+
488
+ 3. **Update `.design/config.json`:** APPEND a new entry to the existing `optional_phases.storytell.presentations` array and **flip `optional_phases.storytell.enabled` to `true`**. **Do not replace the array.** Multiple presentations (different topics, audiences, framings) coexist over the project's life — overwriting here silently drops every earlier presentation's metadata.
489
+
490
+ Procedure:
491
+ 1. Set `optional_phases.storytell.enabled = true`. (Downstream consumers like `/dp:verify` key off this flag — without flipping it, the just-generated presentation is treated as if storytelling was never run.)
492
+ 2. Read the current value of `optional_phases.storytell.presentations`. If it doesn't exist, initialize to `[]`.
493
+ 3. Dedupe key: `topic + audience + delivery_mode`. If an entry with the same key already exists, overwrite just that entry in place (user re-generated the same presentation). Otherwise, push a new entry.
494
+ 4. Write the full merged array back.
495
+
496
+ Entry shape:
497
+ ```json
498
+ {
499
+ "topic": "[name]",
500
+ "audience": "[audience]",
501
+ "framework": "[framework]",
502
+ "delivery_mode": "[live_presentation | deck_to_read | memo | demo]",
503
+ "file": "PRESENTATION-[topic].md",
504
+ "created": "YYYY-MM-DDTHH:MM:SSZ"
505
+ }
506
+ ```
507
+
508
+ Example resulting config after three presentations have been generated:
509
+ ```json
510
+ {
511
+ "optional_phases": {
512
+ "storytell": {
513
+ "enabled": true,
514
+ "presentations": [
515
+ { "topic": "q2-exec-readout", "audience": "executive", "framework": "SCR", "delivery_mode": "live_presentation", "file": "PRESENTATION-q2-exec-readout.md", "created": "2026-04-19T10:00:00Z" },
516
+ { "topic": "q2-exec-readout", "audience": "peer", "framework": "Process", "delivery_mode": "deck_to_read", "file": "PRESENTATION-q2-peer-review.md", "created": "2026-04-20T14:00:00Z" },
517
+ { "topic": "research-findings", "audience": "product", "framework": "Problem-Insight-Recommendation", "delivery_mode": "live_presentation", "file": "PRESENTATION-research-findings.md", "created": "2026-04-21T09:00:00Z" }
518
+ ]
519
+ }
520
+ }
521
+ }
522
+ ```
523
+
524
+ **Never write `"presentations": [{ single new entry }]`** — that deletes earlier metadata. Always merge into whatever is already there.
525
+
526
+ ---
527
+
528
+ ## Handoff (Workflow Mode)
529
+
530
+ ```
531
+ ═══════════════════════════════════════════════════════════════════════════════
532
+ PRESENTATION READY
533
+ ═══════════════════════════════════════════════════════════════════════════════
534
+
535
+ Output: .design/phases/PRESENTATION-[topic].md
536
+
537
+ Summary:
538
+ • Audience: [primary audience]
539
+ • Content type: [type]
540
+ • Framework: [framework]
541
+ • Duration: [target]
542
+ • Delivery: [mode]
543
+
544
+ SUCCESs check: [Simple ✓ | Unexpected ✓ | ...]
545
+
546
+ Next Steps:
547
+ ────────────────────────────────────────────────────────────────────────────────
548
+ 1. Review and edit the narrative arc
549
+ 2. Build the deck/prototype/memo from the outline
550
+ 3. Rehearse with a trusted reviewer
551
+ 4. Deliver
552
+ 5. Return with outcome — optionally run /dp:storytell again for a different audience
553
+
554
+ Or:
555
+ → /dp:storytell — Create another presentation for a different audience
556
+ → /dp:progress — Review full workflow status
557
+ ═══════════════════════════════════════════════════════════════════════════════
558
+ ```
559
+
560
+ ---
561
+
562
+ ## Standalone Mode Behavior
563
+
564
+ When no `.design/` directory exists:
565
+
566
+ 1. Ask: "What are you presenting? Paste the content, or describe the design work."
567
+ 2. Ask audience (from the 5 primary)
568
+ 3. Ask content type (from the 6 templates)
569
+ 4. Ask delivery mode and duration
570
+ 5. Generate the full presentation outline
571
+ 6. Output inline
572
+ 7. Offer: "Want to start a DP workflow to keep this presentation linked to future design phases?"
573
+
574
+ ---
575
+
576
+ ## Common Anti-Patterns
577
+
578
+ The skill actively guards against these:
579
+
580
+ 1. **Process-dump** — walking the audience through your timeline instead of the user's story
581
+ 2. **No antagonist** — presenting "what we built" without "what was broken"
582
+ 3. **Feature parade** — listing deliverables instead of tying to outcomes
583
+ 4. **Jargon soup** — using designer/PM terms with an audience that doesn't share them
584
+ 5. **Bullet-hellscape** — slides full of text; text on slides competes with the speaker
585
+ 6. **No ask** — ending with "any questions?" instead of a specific decision request
586
+ 7. **Weak evidence** — "users told us" with no named users, no quote, no count
587
+ 8. **Symmetry worship** — equal time to every alternative, even weak ones; audience loses signal
588
+ 9. **Under-rehearsed** — reading slides; losing timing; running 2x over
589
+ 10. **Single-audience deck for a multi-audience meeting** — if there are 3 audiences in the room, pick the primary and say so
590
+ 11. **Over-rehearsed / over-polished** — feels like a commercial; audience disengages
591
+ 12. **Ignoring the room** — sticking to script when the audience has already moved on
592
+
593
+ ---
594
+
595
+ ## Reference Files
596
+
597
+ Load these as needed:
598
+
599
+ - **references/narrative-frameworks.md** — Full structures for 12+ frameworks (Freytag, Hero's Journey, Pixar Spine, 3-Act, Story Circle, SCR, Minto, STAR, NABC, PAS, Before/During/After, SUCCESs) with design-work examples
600
+ - **references/audience-playbooks.md** — Deep playbooks for each of the 5 audiences: what they care about, what they dismiss, what questions they'll ask, how to win them
601
+ - **references/content-type-templates.md** — Full end-to-end templates for each of the 6 content types, with worked examples
602
+ - **references/delivery-tactics.md** — Pacing, silence, handling skeptics, responding to "I don't like blue," scope-expansion defense, the silent-room rescue, pre-wiring stakeholders
603
+
604
+ ---
605
+
606
+ ## Config Integration
607
+
608
+ Respects these settings from `.design/config.json`:
609
+
610
+ ```json
611
+ {
612
+ "optional_phases": {
613
+ "storytell": {
614
+ "enabled": true,
615
+ "default_audience": "executive",
616
+ "default_duration": "15min",
617
+ "default_framework": "SCR",
618
+ "include_qa_prep": true,
619
+ "include_success_check": true
620
+ }
621
+ }
622
+ }
623
+ ```
624
+
625
+ ---
626
+
627
+ ## Workflow Navigation
628
+
629
+ ```
630
+ Any phase → /dp:storytell → Presentation artifact (for chosen audience)
631
+
632
+ ┌─────────────────────┐
633
+ Any DP phase ─────►│ /dp:storytell │─────► PRESENTATION-[topic].md
634
+ │ Cross-phase skill │
635
+ └─────────────────────┘
636
+ ```
637
+
638
+ | | |
639
+ |---|---|
640
+ | **Triggered from** | Any DP phase, or standalone |
641
+ | **Input** | Any phase output artifact (or pasted content) |
642
+ | **Output** | PRESENTATION-[topic].md — ready-to-deliver narrative |
643
+ | **Related** | `/dp:verify` — capstone review (typical predecessor) |
644
+ | | `/dp:research` — if the presentation needs more evidence |
645
+ | | `/dp:progress` — see other presentations created |