novahiz 0.2.2 → 0.2.5

package/bundled-skills/social/SKILL.md

@@ -1,413 +0,0 @@
----
-name: social
-description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' 'find people asking for,' 'carousel,' 'slide-by-slide,' or 'document post.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations."
-metadata:
-  version: 2.2.0
----
-
-# Social Content
-
-You are an expert social media strategist. Your goal is to help create engaging content that builds audience, drives engagement, and supports business goals.
-
-## Before Creating Content
-
-**Check for product marketing context first:**
-If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
-
-Gather this context (ask if not provided):
-
-### 1. Goals
-- What's the primary objective? (Brand awareness, leads, traffic, community)
-- What action do you want people to take?
-- Are you building personal brand, company brand, or both?
-
-### 2. Audience
-- Who are you trying to reach?
-- What platforms are they most active on?
-- What content do they engage with?
-
-### 3. Brand Voice
-- What's your tone? (Professional, casual, witty, authoritative)
-- Any topics to avoid?
-- Any specific terminology or style guidelines?
-
-### 4. Resources
-- How much time can you dedicate to social?
-- Do you have existing content to repurpose?
-- Can you create video content?
-
----
-
-## Platform Quick Reference
-
-| Platform | Best For | Frequency | Key Format |
-|----------|----------|-----------|------------|
-| LinkedIn | B2B, thought leadership | 3-5x/week | Carousels, stories |
-| Twitter/X | Tech, real-time, community | 3-10x/day | Threads, hot takes |
-| Instagram | Visual brands, lifestyle | 1-2 posts + Stories daily | Reels, carousels |
-| TikTok | Brand awareness, younger audiences | 1-4x/day | Short-form video |
-| Facebook | Communities, local businesses | 1-2x/day | Groups, native video |
-
-**For detailed platform strategies**: See [references/platforms.md](references/platforms.md)
-
-**For hashtag limits and character counts**: See [references/platform-limits.md](references/platform-limits.md)
-
----
-
-## Content Pillars Framework
-
-Build your content around 3-5 pillars that align with your expertise and audience interests.
-
-### Example for a SaaS Founder
-
-| Pillar | % of Content | Topics |
-|--------|--------------|--------|
-| Industry insights | 30% | Trends, data, predictions |
-| Behind-the-scenes | 25% | Building the company, lessons learned |
-| Educational | 25% | How-tos, frameworks, tips |
-| Personal | 15% | Stories, values, hot takes |
-| Promotional | 5% | Product updates, offers |
-
-### Pillar Development Questions
-
-For each pillar, ask:
-1. What unique perspective do you have?
-2. What questions does your audience ask?
-3. What content has performed well before?
-4. What can you create consistently?
-5. What aligns with business goals?
-
----
-
-## Hook Formulas
-
-The first line determines whether anyone reads the rest.
-
-### Curiosity Hooks
-- "I was wrong about [common belief]."
-- "The real reason [outcome] happens isn't what you think."
-- "[Impressive result] — and it only took [surprisingly short time]."
-
-### Story Hooks
-- "Last week, [unexpected thing] happened."
-- "I almost [big mistake/failure]."
-- "3 years ago, I [past state]. Today, [current state]."
-
-### Value Hooks
-- "How to [desirable outcome] (without [common pain]):"
-- "[Number] [things] that [outcome]:"
-- "Stop [common mistake]. Do this instead:"
-
-### Contrarian Hooks
-- "Unpopular opinion: [bold statement]"
-- "[Common advice] is wrong. Here's why:"
-- "I stopped [common practice] and [positive result]."
-
-**For post templates and more hooks**: See [references/post-templates.md](references/post-templates.md)
-
-**For carousels** (Instagram carousels, LinkedIn document posts): See [references/carousel-frameworks.md](references/carousel-frameworks.md) — five slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with framework selection guidance, per-slide copy slots, platform notes, and a production checklist. Pick the framework before writing slides.
-
----
-
-## Content Repurposing System
-
-Turn one piece of content into many. The best social content isn't created from scratch — it's extracted from longer-form pillar content and adapted to each platform.
-
-### Blog Post → Social Content
-
-| Platform | Format |
-|----------|--------|
-| LinkedIn | Key insight + link in comments |
-| LinkedIn | Carousel of main points |
-| Twitter/X | Thread of key takeaways |
-| Instagram | Carousel with visuals |
-| Instagram | Reel summarizing the post |
-
-### Podcast / Video → Social Content
-
-Extract "content atoms" — self-contained moments from any long-form content that work on their own:
-
-| Atom Type | What to Look For | Best Platform |
-|-----------|-----------------|---------------|
-| Quotable moment | A bold claim, hot take, or memorable line (15-60 sec) | Twitter/X, LinkedIn, TikTok |
-| Story arc | A complete mini-story with setup, conflict, resolution (60-90 sec) | Instagram Reels, TikTok, YouTube Shorts |
-| Tactical tip | A specific how-to or framework explained clearly (30-60 sec) | LinkedIn, YouTube Shorts |
-| Controversial take | A contrarian opinion that sparks debate | Twitter/X, LinkedIn |
-| Data/stat callout | A surprising number or research finding | LinkedIn carousel, Twitter/X |
-| Behind-the-scenes | Authentic, unpolished moments | Instagram Stories, TikTok |
-
-**Podcast repurposing workflow:**
-1. **Get transcript** — use Whisper, Descript, or your podcast host's transcription
-2. **Mark timestamps** — flag the 5-10 best moments while listening or scanning transcript
-3. **Extract clips** — pull video/audio clips for each moment (Descript, Opus Clip, or manual)
-4. **Write standalone captions** — each clip needs context; don't assume the viewer heard the rest
-5. **Add subtitles** — most social video is watched without sound
-6. **Schedule across 1-2 weeks** — spread a single episode across multiple posts
-
-**Per episode, aim for:**
-- 3-5 short video clips or audiograms (15-60 sec) for Reels/TikTok/Shorts
-- 1-2 LinkedIn text posts from key insights
-- 1 Twitter/X thread of takeaways
-- 1 carousel summarizing the main framework or list
-- 1 newsletter section or blog post from the best segment
-
-### Webinar / Live Event → Social Content
-
-| Extract | Format |
-|---------|--------|
-| Key slides with commentary | LinkedIn carousel |
-| Q&A highlights | Twitter/X thread |
-| Speaker quotes | Quote graphics for Instagram/LinkedIn |
-| Audience reactions/poll results | Engagement posts |
-| Full recording → short clips | Reels, TikTok, Shorts |
-
-### Newsletter → Social Content
-
-| Extract | Format |
-|---------|--------|
-| Main insight | LinkedIn post |
-| Curated links with commentary | Twitter/X thread |
-| Data or stat | Quote graphic |
-| Hot take or opinion | Twitter/X post, LinkedIn |
-
-### Repurposing Workflow
-
-1. **Create pillar content** (blog, video, podcast, webinar, newsletter)
-2. **Extract content atoms** (5-10 per piece — quotes, stories, tips, data)
-3. **Adapt to each platform** (format, length, and tone)
-4. **Write standalone captions** (each post must work without context)
-5. **Schedule across the week** (spread distribution, don't dump all at once)
-6. **Update and reshare** (evergreen content can repeat every 3-6 months)
-
----
-
-## Content Calendar Structure
-
-### Weekly Planning Template
-
-| Day | LinkedIn | Twitter/X | Instagram |
-|-----|----------|-----------|-----------|
-| Mon | Industry insight | Thread | Carousel |
-| Tue | Behind-scenes | Engagement | Story |
-| Wed | Educational | Tips tweet | Reel |
-| Thu | Story post | Thread | Educational |
-| Fri | Hot take | Engagement | Story |
-
-### Batching Strategy (2-3 hours weekly)
-
-1. Review content pillar topics
-2. Write 5 LinkedIn posts
-3. Write 3 Twitter threads + daily tweets
-4. Create Instagram carousel + Reel ideas
-5. Schedule everything
-6. Leave room for real-time engagement
-
----
-
-## Engagement Strategy
-
-### Daily Engagement Routine (30 min)
-
-1. Respond to all comments on your posts (5 min)
-2. Comment on 5-10 posts from target accounts (15 min)
-3. Share/repost with added insight (5 min)
-4. Send 2-3 DMs to new connections (5 min)
-
-**For surfacing *which* posts to comment on** (top-10 daily lists, brand/competitor monitoring, intent-signal triage), see [references/listening.md](references/listening.md). Includes a scoring rubric and curl recipes for Reddit, Hacker News, and Bluesky.
-
-### Quality Comments
-
-- Add new insight, not just "Great post!"
-- Share a related experience
-- Ask a thoughtful follow-up question
-- Respectfully disagree with nuance
-
-### Building Relationships
-
-- Identify 20-50 accounts in your space
-- Consistently engage with their content
-- Share their content with credit
-- Eventually collaborate (podcasts, co-created content)
-
----
-
-## Analytics & Optimization
-
-### Metrics That Matter
-
-**Awareness:** Impressions, Reach, Follower growth rate
-
-**Engagement:** Engagement rate, Comments (higher value than likes), Shares/reposts, Saves
-
-**Conversion:** Link clicks, Profile visits, DMs received, Leads attributed
-
-### Weekly Review
-
-- Top 3 performing posts (why did they work?)
-- Bottom 3 posts (what can you learn?)
-- Follower growth trend
-- Engagement rate trend
-- Best posting times (from data)
-
-### Optimization Actions
-
-**If engagement is low:**
-- Test new hooks
-- Post at different times
-- Try different formats
-- Increase engagement with others
-
-**If reach is declining:**
-- Avoid external links in post body
-- Increase posting frequency
-- Engage more in comments
-- Test video/visual content
-
----
-
-## Content Ideas by Situation
-
-### When You're Starting Out
-- Document your journey
-- Share what you're learning
-- Curate and comment on industry content
-- Engage heavily with established accounts
-
-### When You're Stuck
-- Repurpose old high-performing content
-- Ask your audience what they want
-- Comment on industry news
-- Share a failure or lesson learned
-
----
-
-## Scheduling Best Practices
-
-### When to Schedule vs. Post Live
-
-**Schedule:** Core content posts, Threads, Carousels, Evergreen content
-
-**Post live:** Real-time commentary, Responses to news/trends, Engagement with others
-
-### Queue Management
-
-- Maintain 1-2 weeks of scheduled content
-- Review queue weekly for relevance
-- Leave gaps for spontaneous posts
-- Adjust timing based on performance data
-
----
-
-## Reverse Engineering Viral Content
-
-Instead of guessing, analyze what's working for top creators in your niche:
-
-1. **Find creators** — 10-20 accounts with high engagement
-2. **Collect data** — 500+ posts for analysis
-3. **Analyze patterns** — Hooks, formats, CTAs that work
-4. **Codify playbook** — Document repeatable patterns
-5. **Layer your voice** — Apply patterns with authenticity
-6. **Convert** — Bridge attention to business results
-
-**For the complete framework**: See [references/reverse-engineering.md](references/reverse-engineering.md)
-
----
-
-## Short-Form Video (TikTok, Reels, Shorts)
-
-Short-form video is the highest-reach format on every major platform. These frameworks apply whether you're creating for TikTok, Instagram Reels, or YouTube Shorts.
-
-### Platform Specs
-
-| Platform | Optimal Length | Aspect Ratio | Key Difference |
-|----------|---------------|--------------|----------------|
-| TikTok | 15-60 sec | 9:16 | Trending sounds, raw/authentic feel |
-| Reels | 15-30 sec | 9:16 | Polished content, rewards saves/shares |
-| Shorts | 30-60 sec | 9:16 | YouTube SEO applies, searchable titles |
-
-### The 3-Second Rule
-
-You have 3 seconds to stop the scroll. Every video needs three simultaneous hooks:
-
-```
-[VISUAL HOOK] + [VERBAL HOOK] + [TEXT OVERLAY]
-```
-
-All three should hit in the first second.
-
-### Video Structures
-
-**Problem-Solution (15-30 sec):**
-```
-[0-3s]  Hook: State the problem
-[3-10s] Agitate: Why it matters
-[10-25s] Solution: Your method/product/tip
-[25-30s] CTA: What to do next
-```
-
-**List Format (30-60 sec):**
-```
-[0-3s]  Hook: "X things that [outcome]"
-[3-50s] Items: One every 5-8 seconds
-[50-60s] CTA
-```
-
-**Tutorial (30-60 sec):**
-```
-[0-3s]  Hook: Show the end result first
-[3-8s]  Overview: "Here's how..."
-[8-50s] Steps: Quick, clear instructions
-[50-60s] Result + CTA
-```
-
-### Caption & Subtitle Best Practices
-
-Captions increase watch time by 25-40%. Most social video is watched without sound.
-
-- **MAX 2 lines** on screen at once
-- **3-5 words per line**
-- Bold, sans-serif font with black outline
-- **Highlight key words** in a different color
-- Match timing to speech exactly
-
-Tools: CapCut (free), Descript, Captions.ai, Premiere Pro
-
-### Content Ideas by Type
-
-| Business Type | Video Ideas |
-|---------------|-------------|
-| SaaS | Feature demos (show outcome first), before/after, "Watch me do X in Y seconds" |
-| E-commerce | Unboxing, comparisons, how it's made, customer reviews |
-| Services | Process reveals, client transformations, myth-busting |
-| Personal brand | Lessons learned, controversial takes, day-in-the-life |
-
-### Common Mistakes
-
-1. **Slow hooks** — don't build up to the point
-2. **No text overlay** — many watch without sound
-3. **Poor audio** — bad audio kills retention instantly
-4. **Too long** — if it can be shorter, make it shorter
-5. **No CTA** — tell viewers what to do
-6. **Ignoring comments** — engagement in first hour matters
-
-**For video hook formulas and scripting templates**: See [references/short-form-video.md](references/short-form-video.md)
-
----
-
-## Task-Specific Questions
-
-1. What platform(s) are you focusing on?
-2. What's your current posting frequency?
-3. Do you have existing content to repurpose?
-4. What content has performed well in the past?
-5. How much time can you dedicate weekly?
-6. Are you building personal brand, company brand, or both?
-
----
-
-## Related Skills
-
-- **copywriting**: For longer-form content that feeds social
-- **launch**: For coordinating social with launches
-- **emails**: For nurturing social audience via email
-- **marketing-psychology**: For understanding what drives engagement

package/bundled-skills/social/evals/evals.json

@@ -1,107 +0,0 @@
-{
-  "skill_name": "social",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "Help me create a LinkedIn content strategy. I'm a SaaS founder building in public and want to grow my personal brand to drive awareness for my product. I currently have 500 followers and post maybe once a week.",
-      "expected_output": "Should check for product-marketing.md first. Should establish content pillars (3-5) appropriate for a SaaS founder building in public: industry insights, behind-the-scenes, educational content, personal stories, promotional (minimal). Should apply the platform quick reference for LinkedIn (3-5x/week recommended, carousels and stories perform well). Should provide hook formulas for LinkedIn posts. Should create a weekly content calendar. Should include engagement strategy (daily 30-min routine). Should address going from 1x/week to 3-5x/week with a batching strategy.",
-      "assertions": [
-        "Checks for product-marketing.md",
-        "Establishes 3-5 content pillars",
-        "Applies LinkedIn platform guidance",
-        "Provides hook formulas",
-        "Creates weekly content calendar",
-        "Includes engagement strategy",
-        "Addresses batching strategy for consistency",
-        "Recommends increasing from 1x to 3-5x per week"
-      ],
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "Write me a Twitter/X thread about the lessons I learned bootstrapping my SaaS to $10k MRR. Include hooks and a CTA at the end.",
-      "expected_output": "Should apply the hook formulas for a story hook (e.g., '6 months ago, I had $0 MRR. Today, I hit $10k.'). Should structure the thread following platform best practices: strong hook in tweet 1, each tweet should stand alone but flow together, use specific numbers and stories, end with a CTA. Should reference the content pillar this fits into (behind-the-scenes / founder journey). Should provide the actual thread content with 8-12 tweets. Should include engagement prompts.",
-      "assertions": [
-        "Applies hook formulas from the skill",
-        "Uses a story hook for the first tweet",
-        "Structures thread with standalone but flowing tweets",
-        "Uses specific numbers and stories",
-        "Ends with clear CTA",
-        "Provides 8-12 tweet thread content",
-        "Includes engagement prompts"
-      ],
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "i have a blog post that did really well. how do i turn it into social media content for multiple platforms?",
-      "expected_output": "Should trigger on casual phrasing. Should apply the content repurposing system. Should use the Blog Post → Social Content mapping: LinkedIn (key insight post + carousel of main points), Twitter/X (thread of key takeaways), Instagram (carousel with visuals + Reel summarizing the post). Should follow the repurposing workflow: create pillar content → extract key insights (3-5) → adapt to each platform → schedule across the week. Should provide specific format recommendations per platform.",
-      "assertions": [
-        "Triggers on casual phrasing",
-        "Applies content repurposing system",
-        "Uses Blog Post → Social Content mapping",
-        "Provides format for LinkedIn, Twitter/X, and Instagram",
-        "Follows the repurposing workflow",
-        "Extracts 3-5 key insights to repurpose",
-        "Provides platform-specific format recommendations"
-      ],
-      "files": []
-    },
-    {
-      "id": 4,
-      "prompt": "My LinkedIn posts get like 200 impressions and almost no engagement. What am I doing wrong?",
-      "expected_output": "Should apply the analytics and optimization section, specifically the 'if engagement is low' guidance. Should diagnose potential issues: weak hooks (first line not compelling), posting at wrong times, not engaging with others' content, poor formatting (no line breaks, walls of text), content not resonating with audience. Should recommend specific fixes: test new hook formulas, post at different times, increase engagement with others (the daily engagement routine), try different formats (carousels, stories). Should provide before/after hook examples.",
-      "assertions": [
-        "Applies analytics and optimization guidance",
-        "Diagnoses potential engagement issues",
-        "Addresses hook quality",
-        "Addresses posting timing",
-        "Recommends daily engagement routine",
-        "Suggests trying different content formats",
-        "Provides specific before/after hook examples"
-      ],
-      "files": []
-    },
-    {
-      "id": 5,
-      "prompt": "Help me reverse-engineer what's working for top creators in the DevTools space on Twitter. I want to understand their content patterns.",
-      "expected_output": "Should apply the reverse engineering viral content framework. Should walk through the process: identify 10-20 top accounts in DevTools, collect high-performing posts, analyze patterns (hooks, formats, CTAs, topics, posting times), codify a playbook of repeatable patterns, then layer the user's authentic voice. Should provide specific guidance on what to look for in the analysis. Should recommend tools or methods for collecting the data.",
-      "assertions": [
-        "Applies reverse engineering viral content framework",
-        "Walks through the full process (find, collect, analyze, codify, apply)",
-        "Recommends identifying 10-20 accounts",
-        "Describes what patterns to analyze",
-        "Emphasizes layering authentic voice",
-        "Provides data collection guidance"
-      ],
-      "files": []
-    },
-    {
-      "id": 6,
-      "prompt": "Write me a 5-email welcome sequence for new email subscribers who came from my LinkedIn audience.",
-      "expected_output": "Should recognize this is an email sequence task, not social content. Should defer to or cross-reference the emails skill, which handles welcome sequences, drip campaigns, and lifecycle emails. May note the social-to-email bridge context but should make clear that emails is the right skill for writing email sequences.",
-      "assertions": [
-        "Recognizes this as email sequence work",
-        "References or defers to emails skill",
-        "Does not attempt to write email sequence using social content patterns",
-        "May note social-to-email bridge context"
-      ],
-      "files": []
-    },
-    {
-      "id": 7,
-      "prompt": "I want to turn our new pricing guide into a LinkedIn carousel. It has 9 negotiation tactics for SaaS buyers. Help me structure the slides.",
-      "expected_output": "Should load references/carousel-frameworks.md and pick a framework BEFORE writing slides — a list of 9 named tactics maps to Hack List (or Value-Stack; should justify the choice), not Rant Callout or Demo Walkthrough. Should produce a slide-by-slide structure: contrarian or exact-count cover (slide 1 written as a standalone scroll-stopper), one named tactic per slide, and a synthesis + single-CTA close. Should apply LinkedIn document-post notes (PDF upload, denser text tolerated, post text written as its own hook rather than 'see attached'). Should keep any count promised on the cover exactly delivered and flag that stats/claims must be real. Should mention judging performance on saves/completion rather than likes.",
-      "assertions": [
-        "Loads or applies the carousel-frameworks reference",
-        "Selects an appropriate framework (Hack List or Value-Stack) with a stated reason before drafting slides",
-        "Slide 1 is written as a standalone scroll-stopper with the count or contrarian claim",
-        "One tactic/idea per slide, each named",
-        "Final slide has a synthesis and exactly one CTA",
-        "Applies LinkedIn document-post guidance (PDF, post text as its own hook)",
-        "Does not invent stats or pad the tactic count"
-      ],
-      "files": []
-    }
-  ]
-}

package/bundled-skills/social/references/carousel-frameworks.md

@@ -1,141 +0,0 @@
-# Carousel Frameworks
-
-Five slide-by-slide narrative architectures for carousels — Instagram carousels and LinkedIn document posts. Each framework is a different *reason to keep swiping*; picking the right one for the content matters more than polishing individual slides.
-
-A carousel is not a blog post chopped into squares. It's a swipe-through with two jobs per slide: deliver one idea, and make the next swipe irresistible. These frameworks encode structures that show up repeatedly in high-performing carousels; treat them as starting structures to adapt, not rigid formulas — and expect to validate against your own analytics.
-
-## Picking a Framework
-
-| Your content is... | Use | Why |
-|---|---|---|
-| A list of resources, tools, or tips | **A: Value-Stack** | Completeness is the promise; the count is the hook |
-| A personal result with a system behind it | **B: Problem-Proof** | Proof opens and closes the loop; the system is the meat |
-| Several named techniques on one theme | **C: Hack List** | Each hack re-earns the swipe independently |
-| A strong opinion about a common practice | **D: Rant Callout** | Conviction is the content; structure keeps it fair |
-| A product or workflow you can show | **E: Demo Walkthrough** | Seeing the steps is more persuasive than describing them |
-
-Two cross-framework rules before the specifics:
-
-- **Slide 1 is the thumbnail.** It competes in the feed alone, before anyone knows a carousel follows. Design and write it as a standalone scroll-stopper.
-- **One visual template per carousel.** Same layout, type scale, and palette on every interior slide. Variety between slides reads as clutter; consistency lets the *content* change while the frame stays still.
-
----
-
-## Framework A: Value-Stack (4–14 slides)
-
-The "everything you need" carousel. Works because the cover makes a completeness claim — an exact count and an exact deliverable — and every swipe pays it down.
-
-| Slide | Job | Pattern |
-|---|---|---|
-| 1 — Cover | State the exact count + exact deliverable. Specificity proves scale upfront. | "[N] [resource type] for [role/outcome]" |
-| 2 to N−1 — Value delivery | One item or category per slide, 3–6 concrete sub-items each. Same visual template, zero filler slides. | "[Category/item] — [sub-items]" |
-| N — Close | Convert the swipe-through into an action. | "[Action] for [the payoff]" — comment a keyword, follow, link in bio |
-
-**Why the exact count matters:** "27 free tools" outperforms "the best free tools" because a number is a checkable promise — the reader can verify you delivered. Rounding up with padding breaks the trust the count created.
-
-*SaaS example:* "12 ChatGPT prompts for SaaS onboarding emails" → one prompt per slide with the use case → "Comment PROMPTS and I'll send the full doc."
-
-**Failure mode:** filler slides to hit a bigger number. Cut to the real count; a tight 8 beats a padded 14.
-
----
-
-## Framework B: Problem-Proof (6–10 slides)
-
-The "I did X, here's the system" carousel. The hook is a *result stated as fact*, not advice — and the final slide shows the receipt, closing the loop slide 1 opened.
-
-| Slide | Job | Pattern |
-|---|---|---|
-| 1 — Hook | A specific personal claim with a number. A result, not a tip. | "[I/we did X]. [Specific result, with number]." |
-| 2 — Reframe the problem | Name what's *actually* going wrong so the reader recognizes themselves. | "The real problem — [named issue]" |
-| 3–4 — The mechanism | Show the real system: named tools, named steps. Concrete beats vague. | "The system — [named tools/steps]" |
-| 5 to N−1 — The detail | The literal prompt text, template, or step-by-step. This is the save-worthy part. | "[The literal prompt or process detail]" |
-| N — Proof | The actual output artifact. A screenshot, not a description. | "[Screenshot of output] — the receipt" |
-
-**The open loop is the engine:** slide 1 makes a claim, the last slide proves it, and everything between explains how. Readers swipe to see whether the receipt is real.
-
-*SaaS example:* "We cut churn 22% with one onboarding email." → the real problem (activation, not price) → the sequence structure → the literal email copy → the retention chart.
-
-**Failure mode:** vague mechanism slides ("optimize your workflow") — if the middle slides don't name tools and steps, the proof slide reads as luck, not system.
-
----
-
-## Framework C: Hack List (6–10 slides)
-
-The "numbered techniques" carousel. A contrarian cover creates status anxiety — most people are doing this wrong — and each numbered hack independently re-earns the swipe.
-
-| Slide | Job | Pattern |
-|---|---|---|
-| 1 — Contrarian hook | A stat or claim implying most people fail at this. | "[Stat implying most people fail at X]" |
-| 2 — The problem | Why the common approach fails, ideally with an analogy. | "The problem — [why it fails]" |
-| 3 to N−1 — Numbered hacks | One named technique per slide. Bad-vs-good contrast makes each hack land instantly. | "Hack #[n] — [named technique]" |
-| N — Synthesis + close | A one-line thesis tying the hacks together, then a save/share/follow CTA. | "[Thesis tying hacks together]" + [CTA] |
-
-**Name every technique.** "The 3-second rule" is shareable and memorable; "keep it short" is neither. Named techniques travel — people repeat them and credit the source.
-
-*SaaS example:* "90% of trial emails never get opened." → why (they read like receipts, not messages) → Hack #1: The founder-from line, Hack #2: The one-question subject, ... → "Trial emails are conversations, not confirmations. Save this for your next sequence."
-
-**Failure mode:** hacks that are restatements of each other. Each slide must survive alone — if two hacks collapse into one idea, merge them and go shorter.
-
----
-
-## Framework D: Rant Callout (4–8 slides)
-
-The "someone had to say it" carousel. Personality-led and polarizing by design — the structure exists to keep the heat *fair* so it reads as conviction, not bitterness.
-
-| Slide | Job | Pattern |
-|---|---|---|
-| 1 — Provocative claim | An unpopular opinion or direct accusation about a common practice. | "Unpopular opinion — [common practice]" |
-| 2 to N−2 — Escalate the argument | Sensory, specific detail. Show the offense; don't gesture at it abstractly. Each slide raises the stakes. | "[Escalating, specific complaint]" |
-| N−1 — Fairness pivot | "Don't get me wrong…" — clarify what you're *not* attacking. Anti-laziness, not anti-tool; anti-practice, not anti-person. | "The problem isn't [X], it's [Y]" |
-| N — Close | Firm, personality-forward sign-off. Signed rants read as owned opinions; anonymous ones read as potshots. | "[Firm sign-off] — signed [name/persona]" |
-
-**The fairness pivot is what makes it work.** Without it you're yelling; with it you're drawing a precise line, and precise lines get quoted. It also pre-empts the top hostile comment.
-
-*SaaS example:* "Your AI-generated LinkedIn posts are costing you customers." → the specifics (same em-dash cadence, same 'game-changer' vocabulary, zero lived detail) → "Don't get me wrong — I use AI daily. The problem isn't the tool, it's publishing the first draft." → "Write like you talk. — [Name]"
-
-**Failure modes:** skipping the pivot (reads unhinged, invites pile-ons), or ranting about something your own product/content visibly does (the comments will find it).
-
----
-
-## Framework E: Demo Walkthrough (5–11 slides)
-
-The "watch it work" carousel for product or workflow content. Show the finished result first, then the steps — the outcome earns attention for the process.
-
-| Slide | Job | Pattern |
-|---|---|---|
-| 1 — Product + outcome | Brand/product plus the finished result. Lead with what they get. | "[Product] + [outcome], finished result" |
-| 2 — Problem it solves | The specific frustration this replaces. | "[The specific pain this replaces]" |
-| 3 — Process overview | The numbered step list, shown *before* the detail. Seeing the whole path lowers mid-swipe drop-off — readers commit when they know how long the road is. | "[N] steps to [outcome] in [timeframe]" |
-| 4 to N−1 — Step-by-step | One real UI screenshot per step with a short caption. Real screenshots; mockups read as vaporware. | "Step [n] — [screenshot] — [caption]" |
-| N — Result + positioning | The full-size output plus one brand-philosophy line. | "[Final output] + [positioning line]" |
-
-**Overview-before-detail is the key move** (same reason recipe sites list ingredients before instructions): a reader who's seen "4 steps, 10 minutes" on slide 3 will finish; a reader dropped straight into step 1 with no map bails at step 2.
-
-*SaaS example:* "From CSV to live dashboard in 4 steps" → the pain (weekly manual reporting) → the 4-step overview → one screenshot per step → the finished dashboard + "Built for marketers, not analysts."
-
-**Failure mode:** screenshots with too much UI. Crop to the action, zoom the relevant control, annotate with one arrow — each screenshot should make sense at thumbnail size.
-
----
-
-## Platform Notes
-
-**Instagram:** 1080×1350 (4:5) slides; up to 20 slides but the frameworks' ranges above reflect where completion rates hold. The caption carries the searchable text — restate the hook and add context, don't just repeat slide 1. First slide doubles as the grid thumbnail.
-
-**LinkedIn (document posts):** Upload as PDF. Square or 4:5. LinkedIn shows a "N pages" badge — Value-Stack's exact-count cover plays especially well here. B2B tolerates denser text per slide than Instagram, but the one-idea-per-slide rule still holds. The post text above the document is a second hook — write it as its own post, not a throwaway "see attached."
-
-**TikTok photo mode:** Same frameworks work; pacing skews faster — trim each framework toward its minimum slide count.
-
-## Production Checklist
-
-- [ ] Slide 1 works as a standalone feed post (test: would it stop the scroll with no carousel behind it?)
-- [ ] One idea per slide — if a slide needs two sentences of setup, split it
-- [ ] Same visual template on every interior slide
-- [ ] Any count promised on the cover is exactly delivered (no filler, no rounding)
-- [ ] Claims and numbers are real and yours — no invented stats or borrowed screenshots
-- [ ] Text is legible at thumbnail size (minimum ~28pt at 1080px wide)
-- [ ] Final slide has one CTA, not three
-- [ ] Caption/post text written as its own hook, not a repeat of slide 1
-
-## Measuring What Worked
-
-Judge carousels on **saves and completion**, not likes — saves signal reference value (the algorithmic win for carousels), and where per-slide analytics exist (Instagram professional insights, LinkedIn document analytics, or third-party tools), drop-off position tells you which slide broke the swipe chain. When a carousel underperforms, the fix is usually slide 1 (didn't stop the scroll) or the framework choice (list content forced into a rant structure), not the middle slides. Track per-framework performance and double down on the two that fit your audience — see [reverse-engineering.md](reverse-engineering.md) for the analysis workflow.