@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/skill-self-improvement/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: skill-self-improvement
+description: "Weekly self-improvement pipeline for skills. Reads outcome journals, corrections, and content analytics to generate targeted skill mutations."
+---
+
+# Skill Self-Improvement — Weekly Pipeline
+
+Closes the loop between content performance data → skill file improvements.
+
+## Architecture
+
+```
+Monday 10:00 UTC cron fires
+  → Phase 1: Gather — read outcomes, corrections, analytics, skill queue
+  → Phase 2: Score — run eval scoring (weekly-review.mjs)
+  → Phase 3: Analyze — match correction patterns to skill files
+  → Phase 4: Mutate — generate specific skill improvements, queue for approval
+  → Phase 5: Log — record outcomes of the improvement run
+```
+
+## When Triggered
+
+Either by cron (Mondays 10:00 UTC) or manual invocation:
+```bash
+node scripts/self-improve/weekly-review/weekly-review.mjs run
+```
+
+## Phase 1: Gather
+
+Read these data sources:
+
+```bash
+# 1. Outcome journal + eval scores
+node scripts/self-improve/outcome-journal/log-outcome.mjs summary
+node scripts/self-improve/outcome-journal/log-outcome.mjs json
+
+# 2. Active corrections
+cat memory/corrections.md
+
+# 3. Skill queue (unprocessed items)
+cat memory/skill-queue.md
+
+# 4. Content analytics (if available per business)
+# aiwithjai:
+ls businesses/aiwithjai/analytics/reports/ 2>/dev/null
+# nomadixgear:
+ls businesses/nomadixgear-sa/analytics/reports/ 2>/dev/null
+```
+
+## Phase 2: Score
+
+Run the weekly review eval scoring:
+
+```bash
+node scripts/self-improve/weekly-review/weekly-review.mjs score
+```
+
+This returns a JSON score with pass/fail per eval. Any eval that failed gets flagged for mutation in Phase 4.
+
+## Phase 3: Analyze — Match Corrections to Skills
+
+For each correction in the active queue and each "corrected" outcome from the past week:
+
+1. **Extract the core failure pattern** — what specific behavior caused the correction?
+2. **Fuzzy-match against skill index** — which skill(s) should have prevented this?
+3. **If match found** — record "this skill needs an anti-pattern entry"
+4. **If no match** — record "new skill may be needed" with `status: pending-approval`
+
+Correction-to-skill mapping heuristics:
+
+| Correction Pattern | Likely Skill |
+|---|---|
+| Forgot to use tool/skill X | Any skill named X; add trigger phrase |
+| Wrong format for platform | `humanizer` or `platform-formatting` |
+| Content too generic/boring | `hook-generator`, `direct-response-copy` |
+| Forgot lint/typecheck | `self-improve` (add to pre-task check) |
+| Voice doesn't sound human | `humanizer`, `brand-voice` |
+| Wrong dependency assumed | `concierge-post-call` or `remotion-best-practices` |
+| Not checking existing files | `document-review` |
+| Wrong SEO/article format | `seo-content`, `blog-worker` |
+
+## Phase 4: Mutate — Generate Skill Improvements
+
+For each skill identified in Phase 3:
+
+1. **Read the SKILL.md** for the affected skill
+2. **Determine improvement type:**
+   - **ADD_ANTI_PATTERN** — Add a row to the Anti-Patterns table documenting what went wrong
+   - **ADD_TRIGGER** — Add trigger words to the description frontmatter
+   - **ADD_STEP** — Add a verification step to the workflow
+   - **REORDER** — Change the sequence of steps to prevent skip
+   - **REWRITE_PROMPT** — Update a prompt template based on what actually works
+3. **Write the improvement** — Write it to `memory/skill-queue.md` with status `pending-approval`
+   ```
+   ## Improvement — <skill-name> — <timestamp>
+   - **status:** pending-approval
+   - **type:** ADD_ANTI_PATTERN
+   - **file:** .claude/skills/<skill-name>/SKILL.md
+   - **change:** Add anti-pattern: "Agent forgot to use this skill when pattern X appeared"
+   - **evidence:** Correction from <date>: <correction text>
+   ```
+4. **DO NOT auto-edit** — skill files are read-only without human approval
+
+## Phase 5: Log Outcomes
+
+After the pipeline completes, log the result:
+
+```bash
+node scripts/self-improve/outcome-journal/log-outcome.mjs log \
+  "skill-self-improvement weekly run" \
+  success \
+  "" \
+  kestrel
+```
+
+If the pipeline failed (scripts errored, no data, etc.), log as `corrected` or `failed` with the specific issue.
+
+## Phase 6: Auto-Skill Queue Revival
+
+**This is the most important phase if the queue is stale.**
+
+1. Read `memory/skill-queue.md`
+2. Count entries with `status: done` that have actionable correction text
+3. Filter OUT: praise ("this is fucking good", "this is fucking excellent"), non-sequiturs, duplicates
+4. Filter IN: corrections about specific skills or behaviors ("fix the skill", "use the hook generator", "check for skills")
+5. For each actionable entry: change `status: done` → `status: pending`
+6. The auto-skill cron will pick these up on next Monday run
+
+**Filtering examples:**
+- "Fuck yeah! Now we need to develop an X offer" → KEEP (actionable request)
+- "This is fucking good!" → DISCARD (praise)
+- "Fucking fix the skill" → KEEP (vague but actionable — flag for review)
+- "I don't use Claude code" → DISCARD (not a skill issue)
+- "That Landing page is fucking good!" → DISCARD (praise)
+- "who the fuck cares about citations in X?" → KEEP (signals skill needs to respect platform context)
+
+## Known Behaviors
+
+- **First run after setup:** Expect some failing evals because the system was always reporting 100%. This is healthy — it means scoring is finally working.
+- **No analytics data:** Some weeks may have no content analytics. The pipeline still runs on corrections + outcomes alone; analytics are a bonus signal.
+- **Empty queue is success:** If Phase 3 finds nothing actionable, that means skills are working. Log and move on.
+
+## Anti-Patterns
+
+| Mistake | Why Wrong | Fix |
+|---|---|---|
+| Auto-editing skill files | Bypasses human review, can break working skills | Always queue for approval |
+| Ignoring corrections with anger | Frustration signals the most important failures | Extract signal from noise |
+| Only checking corrections file | Outcome journal has richer correction data | Check both sources |
+| Skipping content analytics | Misses the connection between skill quality and content performance | Always check analytics dirs |
+| Marking queue as done without applying | This is what killed the auto-skill system | Never mark done until applied |

package/skills/slideshow-script/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: slideshow-script
+description: "Generate 5 different narrative scripts for visual slideshows from a single positioning angle. Each script uses a different storytelling framework..."
+category: creative
+tier: core
+reads:
+  - brand/positioning.md
+  - brand/audience.md
+  - brand/voice-profile.md
+writes:
+  - marketing/content-specs/*.yaml
+depends-on:
+  - brand-voice
+  - positioning-angles
+  - hook-generator
+triggers:
+  - slideshow script
+  - generate scripts
+  - narrative scripts
+  - content scripts
+  - TikTok scripts
+  - storytelling frameworks
+  - carousel scripts
+allowed-tools:
+  - Bash(mktg status *)
+---
+
+# /slideshow-script — Narrative Script Generation
+
+Generate 5 different narrative scripts from a single positioning angle. Each script uses a different storytelling framework, producing 5 publishable pieces of content instead of 5 variations of 1 script.
+
+For scripting frameworks reference, see [references/frameworks.md](references/frameworks.md).
+For content spec YAML schema, see [references/content-spec-schema.md](references/content-spec-schema.md).
+
+## Why 5 Scripts, Not 5 Layouts
+
+```
+Old model:  1 script × 5 visual layouts = 1 usable output (pick 1, waste 4)
+New model:  5 scripts × 5 visual layouts = 5 usable outputs (post all 5)
+```
+
+Each script has a DIFFERENT narrative, DIFFERENT hook, DIFFERENT proof points. When paired with /paper-marketing, each agent gets a unique script AND a unique design direction.
+
+## Workflow
+
+### Phase 1: Load Brand Context
+
+Read in parallel (if they exist):
+- `brand/positioning.md` — available angles, headlines, proof points
+- `brand/audience.md` — pain points, desires, language patterns
+- `brand/voice-profile.md` — tone, vocabulary, do's/don'ts, signature phrases
+
+If any files are missing, the skill still works — see Progressive Enhancement below for how to handle zero-context and partial-context scenarios.
+
+### Phase 2: Select Positioning Angle
+
+If the user hasn't specified an angle, present the available angles from `brand/positioning.md`:
+
+```
+"Which positioning angle should I write 5 scripts for?"
+
+[List angles from positioning.md with their headlines]
+
+Options:
+1-N. Select a specific angle
+N+1. "Use the primary angle"
+```
+
+### Phase 3: Generate 5 Scripts
+
+For the selected positioning angle, generate 5 narratively distinct scripts — one per framework:
+
+| # | Framework | Structure | Hook Style |
+|---|-----------|-----------|------------|
+| 1 | **AIDA** | Attention → Interest → Desire → Action | Bold claim or question |
+| 2 | **PAS** | Problem → Agitate → Solution | Pain point the audience feels |
+| 3 | **BAB** | Before → After → Bridge | "Life before" vs "life after" |
+| 4 | **Star-Story-Solution** | Hook character → conflict → resolution | Personal/relatable story |
+| 5 | **PAIPS** | Problem → Agitate → Intrigue → Positive → Solution | Pain then curiosity pull |
+
+**PAIPS framework** (Problem → Agitate → Intrigue → Positive → Solution): A 5-phase framework that combines PAS agitation with an "intrigue" phase that hints at the solution before revealing it. The "Positive" phase shows the ideal outcome before the actual solution is presented. See [references/paips-framework.md](references/paips-framework.md) for full breakdown with examples.
+
+**Each script includes:**
+- **Hook** (slide 1) — the first thing seen, must grab in 1-3 seconds
+- **5-7 slides** — each with `type` annotation (stat, anchor_word, emotional_pivot, cascade, cta, logo_intro)
+- **CTA** (final slide) — clear action with URL/handle
+- **Animation hints** — spring preset suggestion per slide (bouncy, smooth, heavy, snappy)
+
+**Script generation rules:**
+- All 5 must use the SAME positioning angle but tell DIFFERENT stories
+- No two scripts should share the same hook
+- Each script should use different proof points from the positioning doc
+- Voice rules from voice-profile.md apply to ALL scripts
+- Slide count can vary (5-9) based on what the narrative needs
+
+### 3a. Generate hooks via hook-generator subagent
+
+Launch 5 parallel subagents — one per framework — via the `task` tool with `subagent_type: general`. Each subagent loads hook-generator and executes Phase 1-6, using the framework to bias hook style.
+
+**Framework → Subagent parameter mapping:**
+
+| Framework | Hook Style | Sentence Strategy Bias |
+|-----------|-----------|----------------------|
+| AIDA | Bold claim or question | Declarative |
+| PAS | Pain point the audience feels | Controversial |
+| BAB | "Life before" vs "life after" | Moment |
+| Star-Story-Solution | Personal/relatable story | Vulnerable |
+| PAIPS | Pain then curiosity pull | Insight |
+
+**Subagent prompt template (fill per framework):**
+
+```
+Load the hook-generator skill and execute the full Phase 1-6 pipeline with this context.
+
+Context:
+- WHO: <target audience from brand>
+- WHAT/WHY: <topic/core insight>
+- Knife: <pain point from brand>
+- Platform: TikTok
+- Brand: <brand name>
+- Target Score: 85
+- Framework: <AIDA | PAS | BAB | Star-Story-Solution | PAIPS>
+- Hook Style: <corresponding hook style from table above>
+
+Return ONLY this JSON array with 1-2 hooks:
+[{"hook":"...","score":<0-100>,"pattern":"...","formula":"..."}]
+```
+
+Each subagent returns 1-2 scored hooks. Assign the highest-scoring hook to the corresponding script. If a subagent fails (quota, timeout), fall back to writing the hook manually following the framework's hook style.
+
+### Phase 4: Match Scripts to Visual Directions
+
+Each script gets a recommended visual direction for /paper-marketing:
+
+| Framework | Best Visual Direction | Why |
+|-----------|---------------------|-----|
+| AIDA | Typographic | Text IS the design, progressive revelation |
+| PAS | Contrast Play / Split | Tension between problem and solution |
+| BAB | Atmospheric | Emotional transformation needs breathing room |
+| Star-Story-Solution | Editorial | Story flow needs magazine-like pacing |
+| Stat-Flip | Data-Led | Numbers are the visual anchors |
+
+These are recommendations — the user can override.
+
+### Phase 5: Present for Approval
+
+Use **AskUserQuestion** to show all 5 scripts with their visual direction:
+
+```
+"Here are 5 narrative scripts for '{angle_name}', each using a different storytelling framework:"
+
+1. **AIDA** (→ Typographic): "{hook}" — Attention grab → feature interest → desire trigger → CTA
+2. **PAS** (→ Contrast Play): "{hook}" — Pain → twist → relief
+3. **BAB** (→ Atmospheric): "{hook}" — Before/after transformation
+4. **Star-Story-Solution** (→ Editorial): "{hook}" — Story arc → resolution
+5. **Stat-Flip** (→ Data-Led): "{hook}" — Shocking stat → reframe
+
+Options:
+1. "All 5 look great" — write all 5 content specs
+2. "Regenerate #{n}" — rewrite a specific script
+3. "Change the angle" — try a different positioning angle
+4. "Edit a script" — modify specific slides
+5. "Only use 3 of these" — select a subset
+```
+
+### Phase 6: Write Content Spec YAMLs
+
+For each approved script, write a structured YAML file:
+
+**Path:** `marketing/content-specs/{project}-{framework}.yaml`
+
+Example: `marketing/content-specs/lumi-aida.yaml`
+
+See [references/content-spec-schema.md](references/content-spec-schema.md) for the full schema.
+
+```yaml
+spec_version: 1
+project: lumi
+content_type: tiktok-slideshow
+scripting_framework: AIDA
+platform:
+  name: tiktok
+  width: 1080
+  height: 1920
+  aspect: "9:16"
+positioning_angle: "The 30-Second Active Gate"
+visual_direction: typographic
+slides:
+  - index: 1
+    type: stat
+    headline: "30"
+    subhead: "seconds."
+    body: null
+    animation_hint: spring_bouncy
+    role: hook
+  - index: 2
+    type: anchor_word
+    headline: "Breathe in"
+    subhead: "That's how long five deep breaths take."
+    body: null
+    animation_hint: spring_heavy
+    role: interest
+  # ... more slides
+  - index: 7
+    type: cta
+    headline: "lumi.com"
+    subhead: "Presence before everything."
+    body: null
+    animation_hint: spring_smooth
+    role: action
+cta:
+  url: "lumi.com"
+  tagline: "Presence before everything."
+  handle: "@lumi"
+voice_constraints:
+  tone: "calm, certain, mindful"
+  avoid: ["hype", "guilt", "exclamation marks"]
+  signature_phrases: ["Take 5 breaths. Unlock your phone.", "Presence before everything."]
+```
+
+### Phase 7: Summary
+
+Report what was written:
+```
+5 content specs written to marketing/content-specs/:
+  1. lumi-aida.yaml (7 slides, Typographic)
+  2. lumi-pas.yaml (6 slides, Contrast Play)
+  3. lumi-bab.yaml (7 slides, Atmospheric)
+  4. lumi-story.yaml (8 slides, Editorial)
+  5. lumi-statflip.yaml (5 slides, Data-Led)
+
+Next: Run /paper-marketing to design each script, or /tiktok-slideshow for the full pipeline.
+```
+
+## Standalone Usage
+
+This skill works independently from any orchestrator:
+- `/slideshow-script` alone → generates scripts for manual design work
+- `/slideshow-script` → `/paper-marketing` → manual export (no video)
+- `/slideshow-script` → `/content-atomizer` → repurpose scripts as text posts
+- `/slideshow-script` → `/email-sequences` → use narratives in email campaigns
+
+## Progressive Enhancement
+
+This skill works at three levels of context:
+
+1. **Zero context** — No brand files. Ask the user for: product name, one-sentence description, target audience, and the key benefit. Generate scripts from that. They'll be generic but functional.
+2. **Partial context** — Only `positioning.md` exists. Generate scripts from the positioning angles. Copy will be accurate but may lack voice personality.
+3. **Full context** — All three brand files exist (`positioning.md`, `audience.md`, `voice-profile.md`). Scripts use the right angles, speak to the right pain points, and sound like the brand.
+
+## Anti-Patterns
+
+- **Same hook across scripts** — The whole point of 5 scripts is 5 chances to grab attention differently. If two scripts start with a question hook, you've wasted one. A viewer who scrolled past hook A might stop for hook B — but only if B looks and sounds different.
+- **Recycled proof points** — Reusing the same stat in multiple scripts means a viewer who sees script 2 after script 1 hears the same argument. Each script should use different proof points from positioning.md so every post adds new information.
+- **Generic voice** — "Transform your life" could be any brand on any platform. Viewers tune it out because they've seen it a thousand times. Using the exact vocabulary and signature phrases from voice-profile.md makes the content feel authored and recognizable.
+- **Platform-specific copy in scripts** — Scripts are the narrative layer, not the design layer. Writing "swipe right" or "link in bio" locks the script to one platform. Keep scripts platform-agnostic so the same narrative works for TikTok, Instagram, YouTube Shorts, or any other format.
+- **Too many slides** — Every slide the viewer must sit through is friction. If a slide doesn't advance the narrative toward the CTA, it's a drop-off point. 5-7 slides usually hits the sweet spot for social content.
+- **Ignoring the framework** — Each framework works because of its specific psychological structure. AIDA builds desire before asking for action. PAS makes pain visceral before offering relief. Blending frameworks dilutes the psychological effect that makes each one work.
+
+## Edge Cases
+
+- **positioning.md missing** — Ask the user: "What's the main angle or benefit you want to highlight?" Use their answer as the positioning angle. Offer to run /positioning-angles to build proper angles.
+- **Only 1-2 proof points available** — Generate fewer scripts (3 instead of 5) and tell the user which frameworks were dropped and why. Quality over quantity.
+- **User wants fewer than 5 scripts** — Respect the request. Ask which frameworks they want, or recommend the best 2-3 for their content type.
+- **User wants a framework not in the list** — Accept custom frameworks. Ask for the structure (what are the phases?) and generate a script following that structure.
+- **Brand voice conflicts with framework** — If the brand voice is "calm, no hype" but PAS requires agitation, dial the agitation to match the voice. Agitate with quiet observations, not exclamation marks.
+
+## Principles
+
+- **5 narratives, not 5 variations** — every output should be publishable
+- **Frameworks enforce diversity** — AIDA and PAS produce fundamentally different stories
+- **Content spec is the contract** — downstream skills read YAML, not prose
+- **Archetype annotations matter** — `type: stat` tells Paper agents AND Remotion what to emphasize
+- **Voice rules are non-negotiable** — all 5 scripts must sound like the brand

package/skills/slideshow-script/references/content-spec-schema.md

@@ -0,0 +1,77 @@
+# Content Spec YAML Schema
+
+The content spec is the shared contract between all skills in the video pipeline. Written by `/slideshow-script`, read by `/paper-marketing` agents, ffmpeg, and Remotion.
+
+## Schema
+
+```yaml
+# Required fields
+spec_version: 1                    # Schema version
+project: string                    # Project name (kebab-case)
+content_type: string               # tiktok-slideshow | instagram-carousel | instagram-post | youtube-short
+scripting_framework: string        # AIDA | PAS | BAB | star-story-solution | stat-flip
+
+# Platform spec
+platform:
+  name: string                     # tiktok | instagram | youtube
+  width: number                    # pixels (1080)
+  height: number                   # pixels (1920 for 9:16, 1350 for 4:5)
+  aspect: string                   # "9:16" | "4:5" | "1:1" | "16:9"
+
+# Brand context
+positioning_angle: string          # Which angle from positioning.md
+visual_direction: string           # typographic | data-led | atmospheric | editorial | bold-minimal | contrast-play | split | structured
+
+# Slide content
+slides:
+  - index: number                  # 1-based slide number
+    type: string                   # stat | anchor_word | emotional_pivot | cascade | cta | logo_intro | comparison | question
+    headline: string | null        # Primary text (can be a number for stat type)
+    subhead: string | null         # Secondary text
+    body: string | null            # Body text (can include Arabic/special characters)
+    label: string | null           # Small section label (e.g., "BREATH SYSTEM")
+    animation_hint: string         # spring_bouncy | spring_smooth | spring_heavy | spring_snappy
+    role: string                   # attention | interest | desire | action | problem | agitate | solution | before | after | bridge | star | story | hook
+
+# CTA (always present)
+cta:
+  url: string                      # Primary URL
+  tagline: string                  # Signature phrase
+  handle: string | null            # Social handle (@username)
+
+# Voice rules (copied from brand)
+voice_constraints:
+  tone: string                     # e.g., "calm, certain, mindful"
+  avoid: string[]                  # Words/patterns to never use
+  signature_phrases: string[]      # Available brand phrases
+```
+
+## File Naming
+
+```
+marketing/content-specs/{project}-{framework}.yaml
+```
+
+Examples:
+- `marketing/content-specs/lumi-aida.yaml`
+- `marketing/content-specs/lumi-pas.yaml`
+- `marketing/content-specs/myapp-stat-flip.yaml`
+
+## Consumers
+
+| Consumer | What They Read | How They Use It |
+|----------|---------------|-----------------|
+| /paper-marketing agents | `slides[].type`, `slides[].headline/subhead/body`, `visual_direction` | Layout decisions, text content, archetype-aware design |
+| ffmpeg (v1/v1.5) | `slides[].index`, `platform.width/height` | Slice coordinates, crossfade timing |
+| Remotion (v2) | `slides[].type`, `slides[].animation_hint`, full slide content | Archetype component selection, spring configs, text |
+| /video-content | `platform`, `cta`, `voice_constraints` | Output format, overlays, TTS voice settings |
+
+## Validation Rules
+
+1. `spec_version` must be `1`
+2. At least 3 slides, at most 12
+3. First slide must have `role: hook` or `role: attention` or `role: problem` or `role: stat`
+4. Last slide must have `type: cta`
+5. Every slide must have at least `headline` OR `body`
+6. `animation_hint` must be one of: `spring_bouncy`, `spring_smooth`, `spring_heavy`, `spring_snappy`
+7. `type` must be one of: `stat`, `anchor_word`, `emotional_pivot`, `cascade`, `cta`, `logo_intro`, `comparison`, `question`

package/skills/slideshow-script/references/frameworks.md

@@ -0,0 +1,84 @@
+> **Note:** Examples below use fictional brands (Acme, Lumi, Helm). Replace with your own brand context.
+
+# Slideshow Scripting Frameworks
+
+## AIDA — Attention, Interest, Desire, Action
+
+**Structure:**
+1. **Attention** (Slide 1): Bold claim, shocking stat, or provocative question
+2. **Interest** (Slides 2-3): Explain the mechanism, share the "how"
+3. **Desire** (Slides 4-5): Show the outcome, paint the picture of "after"
+4. **Action** (Slides 6-7): Clear CTA with URL/handle
+
+**Best for:** Broad awareness, product introductions, feature showcases
+**Visual pairing:** Typographic — progressive text revelation matches the framework's build-up
+
+**Example pattern:**
+- "30 seconds." → "That's how long 5 deep breaths take." → "Your phone opens when your breath is done." → "lumi.app"
+
+## PAS — Problem, Agitate, Solution
+
+**Structure:**
+1. **Problem** (Slide 1-2): Name the pain the audience knows
+2. **Agitate** (Slides 3-4): Make the pain worse, show consequences
+3. **Solution** (Slides 5-7): Introduce the fix, prove it works, CTA
+
+**Best for:** Pain-driven products, alternatives to existing solutions, "there's a better way"
+**Visual pairing:** Contrast Play or Split — tension between problem and solution halves
+
+**Example pattern:**
+- "Every app blocker just makes you wait." → "Wait. Or breathe. Or read quotes. None of it sticks." → "Lumi makes you take a real pause. Then your phone opens."
+
+## BAB — Before, After, Bridge
+
+**Structure:**
+1. **Before** (Slides 1-2): Current reality (relatable struggle)
+2. **After** (Slides 3-4): Dream state (what life looks like solved)
+3. **Bridge** (Slides 5-7): How to get there (the product), CTA
+
+**Best for:** Transformation stories, lifestyle products, habit change
+**Visual pairing:** Atmospheric — emotional transformation needs breathing room
+
+**Example pattern:**
+- "My phone was the first thing I touched every morning." → "Now my breath is." → "Lumi is the bridge."
+
+## Star-Story-Solution
+
+**Structure:**
+1. **Star** (Slide 1): Introduce a relatable character or persona
+2. **Story** (Slides 2-5): Take them through a conflict or journey
+3. **Solution** (Slides 6-7): The product resolves the story, CTA
+
+**Best for:** Emotional connection, community-building, personal narratives
+**Visual pairing:** Editorial — story flow needs magazine-like pacing with asymmetric text
+
+**Example pattern:**
+- "Maya unlocks her phone 150 times a day." → "One day she set Lumi. Five deep breaths before each unlock." → "Now her first act is presence."
+
+## Stat-Flip
+
+**Structure:**
+1. **Stat** (Slide 1-2): Surprising, specific data point
+2. **Flip** (Slides 3-4): Reframe the stat, challenge assumptions
+3. **CTA** (Slides 5-6): Clear call to action anchored in the data
+
+**Best for:** Data-driven audiences, proof points, credibility building
+**Visual pairing:** Data-Led — giant numbers as visual anchors, text supports the data
+
+**Example pattern:**
+- "You unlock your phone 150 times a day." → "That's 150 chances to take a breath." → "Lumi turns screen time into breath time."
+
+## Slide Type Reference
+
+Each slide should be annotated with one of these types:
+
+| Type | Visual Treatment | Animation |
+|------|-----------------|-----------|
+| `stat` | Giant number (300px+), small label | Spring bouncy, counter tick |
+| `anchor_word` | One massive word fills slide | Spring heavy/snappy |
+| `emotional_pivot` | Centered text, generous whitespace | Smooth, glow pulse |
+| `cascade` | Sequential lines, left-aligned | Smooth, staggered reveal |
+| `cta` | Centered, ornamental, URL prominent | Smooth, sequential fade |
+| `logo_intro` | Logo centered, clean backdrop | Spring bouncy, sparkle |
+| `comparison` | Split layout, two zones | Slide transition |
+| `question` | Large text with ? or ... | Smooth fade |

package/skills/slideshow-script/references/paips-framework.md

@@ -0,0 +1,37 @@
+# PAIPS Framework
+
+A 5-step copy framework for persuasive short-form content. Use for tweets, short-form video scripts, and carousel copy where you need agitation before the solution.
+
+## The 5 Steps
+
+### 1. Problem — Highlight something painful
+The first line highlights a painful problem that people experience. This line is intended to elicit a strong emotional response and get the reader to the next line.
+
+### 2. Agitate — Agitate the pain
+Next, get under the reader's skin and make them agitated. Once someone is agitated, they are much more likely to be open to a solution.
+
+### 3. Intrigue — Introduce something intriguing
+Introduce something that makes them think, "Wait, what's that?" Get the audience to lean in with interest to carry them through the content.
+
+### 4. Positive Future — Paint a positive future
+Paint a picture of what a positive future would look like. The positive future is tied to something intriguing.
+
+### 5. Solution — Present your solution
+Introduce the solution which should be tied to the problem.
+
+## Usage in Scripts
+
+When using PAIPS for a slideshow script:
+- Slides 1-2: Problem + Agitate (establish the pain)
+- Slide 3: Intrigue (the "wait, what?" moment)
+- Slides 4-5: Positive Future + Solution (deliver the payoff)
+
+## Writing Constraints (from PAIPS source)
+- Break up sentences longer than 25 words
+- Hook sentence must answer: "How will this help me?" or "What will I learn?" or "Is this worth my time?"
+- Mix 3-4 short (7-15 word) sentences with one longer (15-25 word) sentence
+- Use transition words: However, Anyway, More than that, But
+- Use bullets when applicable
+- Short, simple, easy-to-read sentences
+- Do not repeat concepts
+- Do not use "unleash", "unlock", or "imagine"