@strategicnerds/slide-nerds 0.1.0

package/skills/narrative-frameworks/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: narrative-frameworks
+description: Storytelling structures for business presentations -- SCQA, Minto Pyramid, PAS, BAB, and other proven frameworks
+---
+
+# Narrative frameworks skill
+
+Use this skill when structuring a deck's narrative arc. Each framework here defines a specific slide sequence. Pick one framework per deck. Do not mix frameworks within the same presentation.
+
+The deck-templates skill covers complete deck types (investor pitch, product launch, etc.). This skill covers the narrative structure beneath any deck type. A board update can use SCQA. A sales deck can use PAS. A keynote can use Duarte Sparkline. The framework is independent of the content.
+
+## SCQA (Situation, Complication, Question, Answer)
+
+Origin: Barbara Minto / McKinsey. The standard consulting narrative structure.
+
+Use for: board updates, executive recommendations, strategy proposals, any presentation where you are recommending a course of action.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title, date, presenter |
+| 2 | Body text | **Situation**: The stable, agreed-upon context. "We have 2,400 customers and $4.2M ARR." |
+| 3 | Body text with emphasis | **Complication**: What changed or what threatens the status quo. "Enterprise win rate dropped from 40% to 18% in Q4." |
+| 4 | Big stat or section divider | **Question**: The strategic question this creates. "How do we rebuild the enterprise pipeline before Series B?" |
+| 5-10 | Mixed (charts, frameworks, tables) | **Answer**: Your recommendation with supporting evidence. 3-5 slides of analysis. |
+| 11 | Summary or action items | Next steps, decision needed, timeline |
+
+### When SCQA works
+
+- The audience is busy (executives, board members)
+- You need a decision or approval
+- The situation is complex but the recommendation is clear
+- You want to build agreement before revealing the answer
+
+### When SCQA fails
+
+- The audience already knows the situation (skip S, start at C)
+- There is no clear complication (it becomes a status update, not a story)
+
+### SCQA rules
+
+- The Situation must be something everyone agrees on. If it is debatable, it is not a situation.
+- The Complication must create tension. If the audience does not feel concerned, it is not a complication.
+- The Question must be the question the audience would ask after hearing the complication.
+- The Answer must be specific and actionable. "We should invest in enterprise sales" is too vague.
+
+## SCR (Situation, Complication, Resolution)
+
+Origin: McKinsey simplified variant. Drops the explicit Question.
+
+Use for: shorter presentations, quick decision requests, internal updates.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title |
+| 2 | Body text | **Situation**: Current state in 1-2 sentences |
+| 3 | Body text or chart | **Complication**: What threatens the situation |
+| 4-8 | Mixed | **Resolution**: What to do about it, with evidence |
+| 9 | Action items | Next steps |
+
+### SCR vs SCQA
+
+SCR is faster. Use it when the question is obvious from the complication. If you say "enterprise win rate dropped 50%," the question "how do we fix it?" is implicit.
+
+## Minto Pyramid (answer first)
+
+Origin: Barbara Minto, "The Pyramid Principle." The gold standard for executive communication.
+
+Use for: any executive presentation. Board decks. Consulting deliverables. Strategy recommendations.
+
+### Structure
+
+Lead with your answer. Then support it with arguments. Then back each argument with evidence. The audience gets the conclusion on slide 2, not slide 45.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title |
+| 2 | Section divider or big stat | **The answer**: Your recommendation or key finding in one sentence |
+| 3 | Section divider | **Argument 1** heading |
+| 4-5 | Charts/data | Evidence supporting argument 1 |
+| 6 | Section divider | **Argument 2** heading |
+| 7-8 | Charts/data | Evidence supporting argument 2 |
+| 9 | Section divider | **Argument 3** heading |
+| 10-11 | Charts/data | Evidence supporting argument 3 |
+| 12 | Summary | Restate the answer with the three supporting arguments |
+| 13 | Action items | Next steps |
+
+### Pyramid rules
+
+- The answer comes first. Always. If the building catches fire during your presentation, the audience already has the conclusion.
+- Arguments must be MECE (Mutually Exclusive, Collectively Exhaustive). No overlap between arguments. Together they cover the full case.
+- Three arguments is the standard. Two feels thin. Four starts to lose structure.
+- Each argument slide uses an "action title" that states the conclusion, not the topic. "Enterprise revenue grew 3x after adding outbound sales" not "Enterprise revenue."
+
+## Problem-Agitate-Solve (PAS)
+
+Origin: Copywriting framework adapted for presentations.
+
+Use for: sales decks, product pitches, fundraising, any persuasive presentation.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title |
+| 2-3 | Body text, big stat | **Problem**: Define the pain point the audience faces. Use a stat to quantify it. |
+| 4-5 | Body text, quote | **Agitate**: Amplify the pain. Show what happens if the problem is not solved. Cost of inaction. Competitive risk. Customer quotes about the pain. |
+| 6 | Section divider | Transition to solution |
+| 7-10 | Product screenshots, charts, demo | **Solve**: Your solution and proof it works. Features, case studies, data. |
+| 11 | Social proof | Customer logos, testimonials |
+| 12 | CTA | Next steps, pricing, trial |
+
+### PAS rules
+
+- Spend more time on Problem and Agitate than on Solve. The audience must feel the pain before they care about the fix.
+- The Agitate phase is not about fear-mongering. It is about making the cost of inaction concrete. "This costs your team 14 hours per week" is agitation. "Everything will fall apart" is fear-mongering.
+- The transition to Solve should feel like relief, not a sales pitch.
+
+## Before-After-Bridge (BAB)
+
+Origin: Marketing framework.
+
+Use for: transformation stories, product impact, case studies, internal change communication.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title |
+| 2-3 | Body text, stats | **Before**: The current painful state. Quantify with data. |
+| 4-5 | Body text, vision | **After**: The desired future state. Paint the picture of what success looks like. |
+| 6-10 | Mixed | **Bridge**: How to get from Before to After. Your product/plan/strategy is the bridge. |
+| 11 | Summary | Recap the transformation |
+
+### BAB vs PAS
+
+BAB is aspirational. PAS is pain-driven. Use BAB when the audience is already aware of the problem and needs to see the destination. Use PAS when the audience does not yet feel the urgency.
+
+## What-So What-Now What
+
+Origin: Military after-action reviews, adapted for business.
+
+Use for: data presentations, quarterly reviews, post-mortem readouts, research findings.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Title | Deck title |
+| 2-4 | Charts, tables, data | **What**: Present the facts. Revenue numbers, user metrics, experiment results. No interpretation yet. |
+| 5-7 | Analysis, insights | **So What**: Explain why it matters. What does the data mean? What are the implications? |
+| 8-10 | Recommendations | **Now What**: Recommended actions based on the analysis. Specific next steps with owners and timelines. |
+
+### What-So What-Now What rules
+
+- The "What" section must be pure data. No opinions, no recommendations.
+- The "So What" section is where interpretation lives. This is where your expertise shows.
+- The "Now What" section must be actionable. Names, dates, owners.
+- This framework works for any presentation that starts with data and ends with decisions.
+
+## Duarte Sparkline
+
+Origin: Nancy Duarte, "Resonate." The structure behind the best keynotes.
+
+Use for: keynotes, vision presentations, change management, any presentation that needs to inspire action.
+
+### Structure
+
+Alternate between "what is" (the current state) and "what could be" (the future state) throughout the presentation. The contrast creates emotional momentum. End with "the new bliss" -- a vision of the transformed world.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Hook | Open with a story, stat, or question |
+| 2 | What is | Current reality (the problem, the limitation) |
+| 3 | What could be | Vision of the better world |
+| 4 | What is | A deeper look at the current state (data, evidence) |
+| 5 | What could be | More detail on the vision (case study, demo) |
+| 6 | What is | The stakes (what happens if we do not change) |
+| 7 | What could be | The path forward (how we get there) |
+| 8 | What is | Specific obstacle or challenge |
+| 9 | What could be | How the obstacle is overcome |
+| 10 | The new bliss | Final vision. The call to action. What the world looks like when the audience acts. |
+
+### Sparkline rules
+
+- Each "what is" lowers the audience's emotional state. Each "what could be" raises it.
+- The contrast is what creates energy. If everything is positive, the audience disengages.
+- The final "new bliss" must be higher than any previous "what could be." The presentation builds to a crescendo.
+- This framework requires a strong speaker. It does not work as a read-ahead document.
+
+## Monroe's Motivated Sequence
+
+Origin: Alan Monroe, 1930s. The classic persuasion structure.
+
+Use for: proposals, internal pitches, any time you need the audience to take a specific action.
+
+### Slide sequence
+
+| Slide | Type | Content |
+|---|---|---|
+| 1 | Hook | **Attention**: Grab attention with a startling stat, story, or question |
+| 2-3 | Problem statement | **Need**: Establish the problem. Show evidence it is real and urgent. |
+| 4-6 | Solution | **Satisfaction**: Present your solution. Show how it meets the need. |
+| 7-8 | Vision | **Visualization**: Paint a picture of the world with your solution adopted. Show the positive outcome AND the negative outcome of inaction. |
+| 9 | CTA | **Action**: Tell the audience exactly what to do next. Be specific. |
+
+## The Rule of Three
+
+Not a full framework but a structural principle that enhances any framework.
+
+### The rule
+
+Organize content into groups of three. Three arguments. Three features. Three stats. Three slides per section. The human brain processes groups of three naturally.
+
+### Application
+
+- **Three supporting arguments** in a Minto Pyramid
+- **Three pain points** in a PAS deck
+- **Three pillars** in a strategy presentation
+- **Three case studies** in a sales deck
+- **Three stats** on a big-number slide
+
+If you have four points, see if one can be cut or merged. If you have two, see if a third adds meaningful support. Three is almost always right.
+
+## Framework selection guide
+
+| Situation | Framework | Why |
+|---|---|---|
+| Recommending a decision to executives | SCQA or Minto Pyramid | Answer-first respects their time |
+| Quarterly data review | What-So What-Now What | Data first, then interpretation, then action |
+| Sales pitch | PAS | Pain creates urgency |
+| Product demo | BAB | Show the transformation |
+| Keynote / vision presentation | Duarte Sparkline | Emotional momentum through contrast |
+| Internal proposal | Monroe's Motivated Sequence | Classic persuasion structure |
+| Quick executive update | SCR | Compressed version of SCQA |
+
+## Common mistakes
+
+- Burying the recommendation. In business, the answer comes first unless you are building a case for a controversial conclusion.
+- Mixing frameworks within one deck. Pick one and commit.
+- Spending too many slides on context. The audience's patience is shorter than you think.
+- Using PAS for internal audiences who already feel the pain. They do not need to be agitated. They need a solution.
+- Treating the framework as a rigid template. Frameworks are starting points. Adapt slide count and depth to the content and audience.

package/skills/react-component-embeds/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: react-component-embeds
+description: Build slides that embed reusable React components and live product demos directly inside section[data-slide] blocks
+---
+
+# React component embeds skill
+
+Use this skill when a slide should host real React UI, not static markup. The goal is to keep demos composable, testable, and safe for presentation flow.
+
+## When to use
+
+Use this skill when the user asks for any of the following:
+
+- Embed an app component directly inside a slide
+- Turn a slide into a live demo surface
+- Reuse an existing feature component inside presentation content
+- Add interactive controls, local state, or network-backed UI in a slide
+
+If the request is only static content, use layout or slide-type skills instead.
+
+## Core pattern
+
+1. Keep the slide shell simple (`section[data-slide]` plus layout container).
+2. Move demo logic into a named React component.
+3. Pass data through props, avoid global mutation.
+4. Keep keyboard interactions compatible with deck navigation.
+5. Add `data-notes` fallback instructions for offline or failure mode.
+
+```tsx
+const ProductDemo: React.FC<{ initialQuery: string }> = ({ initialQuery }) => {
+  const [query, setQuery] = useState(initialQuery)
+
+  return (
+    <div className="card-surface p-6">
+      <label className="text-sm" htmlFor="demo-query">Search</label>
+      <input
+        id="demo-query"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+        className="mt-2 w-full rounded border px-3 py-2"
+      />
+    </div>
+  )
+}
+
+<section data-slide="">
+  <div className="flex flex-col w-full" style={{ padding: '4rem 6rem' }}>
+    <p className="section-label mb-3">Live demo</p>
+    <h2 className="text-[2.5rem] font-bold mb-8">Search behavior in production UI</h2>
+    <ProductDemo initialQuery="onboarding" />
+    <div data-notes="">
+      If the API is unavailable, switch to cached demo data and continue narration.
+    </div>
+  </div>
+</section>
+```
+
+## Interaction guardrails
+
+- Stop slide-level keybindings while typing by using native `input`, `textarea`, or contentEditable elements.
+- Keep heavy fetches lazy. Start data loading when the slide mounts or on explicit user action.
+- For external systems, include a local fallback state so the deck can still run offline.
+- Use small component boundaries so demos can be tested with React Testing Library.
+
+## Quality checklist
+
+Before finishing a slide with embedded components, verify:
+
+- The component renders correctly inside `section[data-slide]`.
+- User interaction works with mouse and keyboard.
+- Slide navigation still works after interaction.
+- Failure path is documented in `data-notes`.
+- The demo can be reused outside slides without runtime-specific assumptions.