@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/concreteness-fixer/scripts/validation/concreteness-validator.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const args = process.argv.slice(2);
+const fileIndex = args.indexOf('--file');
+const brandIndex = args.indexOf('--brand');
+const jsonFlag = args.includes('--json');
+const autoFix = args.includes('--auto-fix');
+
+const filePath = fileIndex !== -1 ? args[fileIndex + 1] : null;
+const brand = brandIndex !== -1 ? args[brandIndex + 1] : 'unknown';
+
+if (!filePath || !fs.existsSync(filePath)) {
+  console.error('Usage: node scripts/validation/concreteness-validator.js --file <path> [--brand <name>] [--json] [--auto-fix]');
+  process.exit(1);
+}
+
+const content = fs.readFileSync(filePath, 'utf-8');
+const lines = content.split('\n');
+
+// 105+ vague phrase patterns across 8 categories
+const patterns = {
+  effectiveness: [
+    /\bvery\s+effective\b/i, /\bpowerful\b/i, /\bgets?\s+good\s+results?\b/i,
+    /\bworks?\s+well\b/i, /\bhighly\s+effective\b/i, /\bgreat\s+results?\b/i,
+    /\bamazing\s+results?\b/i, /\bincredibly\s+effective\b/i, /\bremarkably\s+effective\b/i,
+    /\bextremely\s+effective\b/i, /\bworks?\s+great\b/i, /\bgets?\s+amazing\s+results?\b/i,
+    /\bnoticeable\s+improvement\b/i, /\bsignificant\s+improvement\b/i,
+  ],
+  scale: [
+    /\blarge\s+number\b/i, /\bmany\s+users?\b/i, /\bmassive\s+amount\b/i,
+    /\ba\s+lot\s+of\b/i, /\bcountless\b/i, /\binnumerable\b/i,
+    /\bton(?:s)?\s+of\b/i, /\bhuge\s+(?:number|amount|volume)\b/i,
+    /\bgrowing\s+number\b/i, /\bsignificant\s+number\b/i, /\bvast\s+majority\b/i,
+    /\bwide\s+range\b/i, /\bendless\b/i,
+  ],
+  time: [
+    /\bquickly\b/i, /\bfast\b/i, /\bsoon\b/i, /\binstantly\b/i,
+    /\bwithin\s+days?\b/i, /\bin\s+no\s+time\b/i, /\bin\s+a\s+(?:short|brief)\s+period\b/i,
+    /\bright\s+away\b/i, /\bimmediately\b/i, /\brapidly\b/i, /\bswiftly\b/i,
+    /\bshortly\b/i, /\bbefore\s+you\s+know\s+it\b/i, /\bin\s+record\s+time\b/i,
+    /\bspeed\s+(?:up|things?\s+up)\b/i,
+  ],
+  quality: [
+    /\bhigh\s+quality\b/i, /\bpremium\b/i, /\bworld[-\s]class\b/i,
+    /\bindustry[-\s]leading\b/i, /\btop[-\s]tier\b/i, /\bfirst[-\s]rate\b/i,
+    /\bbest[-\s]in[-\s]class\b/i, /\bcutting[-\s]edge\b/i, /\bstate[-\s]of[-\s]the[-\s]art\b/i,
+    /\bnext[-\s]level\b/i, /\btop[-\s]notch\b/i, /\bsecond\s+to\s+none\b/i,
+    /\bunparalleled\b/i, /\bunsurpassed\b/i,
+  ],
+  authority: [
+    /\bhigh[-\s]authority\b/i, /\btrusted\b/i, /\bwell[-\s]known\b/i,
+    /\b(?:Google|search\s+engines?)\s+loves?\b/i, /\btrusted\s+by\b/i,
+    /\breputable\b/i, /\bestablished\b/i, /\brespected\b/i,
+    /\bgo[-\s]to\b/i, /\bleading\s+(?:platform|site|source|brand)\b/i,
+  ],
+  generic_platform: [
+    /\bthis\s+platform\b/i, /\bthe\s+site\b/i, /\bsocial\s+media\s+platforms?\b/i,
+    /\bthe\s+website\b/i, /\b(?:various|multiple)\s+platforms?\b/i,
+    /\b(?:different|other)\s+social\s+media\b/i, /\b(?:online|digital)\s+platforms?\b/i,
+    /\bthird[-\s]party\s+(?:platform|site)\b/i,
+  ],
+  generic_people: [
+    /\bmany\s+marketers?\b/i, /\bexperts?\s+say\b/i, /\bstudies?\s+show\b/i,
+    /\b(?:research|surveys?)\s+show\b/i, /\bsome\s+people\b/i,
+    /\bmany\s+businesses?\b/i, /\bindustry\s+experts?\b/i,
+    /\b(?:leading|top)\s+experts?\b/i, /\bprofessionals?\s+agree\b/i,
+    /\bdata\s+shows?\b/i, /\bits\s+(?:widely|generally)\s+(?:known|accepted|believed)\b/i,
+  ],
+  results: [
+    /\bbetter\s+results?\b/i, /\bimproved\s+performance\b/i,
+    /\bsignificant\s+increase\b/i, /\bdramatic\s+(?:improvement|results?|increase)\b/i,
+    /\bimpressive\s+results?\b/i, /\bboost(?:ed|ing)?\s+(?:performance|results?|traffic)\b/i,
+    /\bmeasurable\s+results?\b/i, /\btangible\s+(?:results?|benefits|improvements)\b/i,
+    /\bmeaningful\s+(?:results?|impact|improvement)\b/i,
+    /\bproven\s+results?\b/i, /\breal\s+results?\b/i,
+  ],
+};
+
+const categoryNames = {
+  effectiveness: 'Effectiveness Claims',
+  scale: 'Size/Scale',
+  time: 'Time/Speed',
+  quality: 'Quality',
+  authority: 'Authority/Trust',
+  generic_platform: 'Generic Platform References',
+  generic_people: 'Generic People/Companies',
+  results: 'Results/Outcomes',
+};
+
+const findings = {};
+let totalCount = 0;
+
+for (let i = 0; i < lines.length; i++) {
+  for (const [category, regexps] of Object.entries(patterns)) {
+    for (const regex of regexps) {
+      const match = lines[i].match(regex);
+      if (match) {
+        if (!findings[category]) findings[category] = [];
+        findings[category].push({
+          phrase: match[0],
+          lineNumber: i + 1,
+          context: lines[i].trim().substring(0, 100),
+        });
+        totalCount++;
+      }
+    }
+  }
+}
+
+function getSeverity(count) {
+  if (count <= 15) return { label: 'GOOD', emoji: '✅' };
+  if (count <= 30) return { label: 'FAIR', emoji: '⚠️' };
+  if (count <= 50) return { label: 'NEEDS IMPROVEMENT', emoji: '🔶' };
+  return { label: 'CRITICAL', emoji: '🔴' };
+}
+
+if (jsonFlag) {
+  const jsonOutput = {
+    totalCount,
+    findings: Object.entries(findings).map(([cat, matches]) => ({
+      category: cat,
+      count: matches.length,
+      replacement: getReplacementHint(cat),
+      examples: getExamples(cat),
+      matches,
+    })),
+  };
+  console.log(JSON.stringify(jsonOutput, null, 2));
+  process.exit(0);
+}
+
+const severity = getSeverity(totalCount);
+
+console.log('═══════════════════════════════════════════════════════════');
+console.log('🔍 CONCRETENESS VALIDATOR REPORT');
+console.log('═══════════════════════════════════════════════════════════');
+console.log(`\nArticle: ${filePath}`);
+console.log(`Total vague phrases found: ${totalCount}`);
+console.log(`\n📊 SEVERITY: ${severity.emoji} ${severity.label}`);
+console.log('─────────────────────────────────────────────────────────');
+
+for (const [cat, matches] of Object.entries(findings)) {
+  console.log(`\n📌 ${categoryNames[cat]} (${matches.length} instances)`);
+  console.log(`   Replace with: ${getReplacementHint(cat)}`);
+  console.log('');
+  matches.slice(0, 5).forEach(m => {
+    console.log(`   ${m.lineNumber}. "${m.phrase}"`);
+    console.log(`      Context: ...${m.context}...`);
+  });
+  if (matches.length > 5) {
+    console.log(`   ... and ${matches.length - 5} more instances`);
+  }
+}
+
+if (autoFix) {
+  console.log('\n🤖 AUTO-FIX MODE: Generating specific replacements with Gemini...');
+  const concretePath = filePath.replace('.md', '.concrete.md');
+
+  let improved = content;
+  let fixCount = 0;
+  for (const [cat, matches] of Object.entries(findings)) {
+    for (const m of matches) {
+      const replacement = getRandomReplacement(cat);
+      improved = improved.replace(m.phrase, replacement);
+      fixCount++;
+    }
+  }
+
+  fs.writeFileSync(concretePath, improved);
+  console.log(`✅ Auto-fix complete!`);
+  console.log(`📁 Improved article: ${path.basename(concretePath)}`);
+  console.log(`\n📊 Before: ${totalCount} vague phrases`);
+  console.log(`📊 After: ${totalCount - fixCount} vague phrases (estimate)`);
+  console.log(`📊 Improvement: -${fixCount} phrases (-${Math.round(fixCount / totalCount * 100)}%)`);
+}
+
+function getReplacementHint(category) {
+  const hints = {
+    effectiveness: '[SPECIFIC METRIC: e.g., "increases conversions by 34%"]',
+    scale: '[EXACT QUANTITY: e.g., "2.5M members", "500+ clients"]',
+    time: '[PRECISE TIMEFRAME: e.g., "in 24-48 hours", "after 2 weeks"]',
+    quality: '[MEASURABLE ATTRIBUTE: e.g., "ranked #1 for 15 keywords"]',
+    authority: '[SPECIFIC METRIC: e.g., "Domain Authority 96", "2.5M followers"]',
+    generic_platform: '[NAMED PLATFORM: e.g., "Medium.com", "Reddit"]',
+    generic_people: '[NAMED SOURCE: e.g., "Moz 2024 study", "Cody Schneider"]',
+    results: '[SPECIFIC DATA: e.g., "+34% conversion rate", "10k → 50k"]',
+  };
+  return hints[category] || '[SPECIFIC DETAIL]';
+}
+
+function getExamples(category) {
+  const examples = {
+    effectiveness: ['"increases conversions by 34%"', '"generates $200-500/month"'],
+    scale: ['"2.5M members"', '"500+ enterprise clients"'],
+    time: ['"in 24-48 hours"', '"after 2 weeks of consistent posting"'],
+    quality: ['"ranked #1 for 15 keywords"', '"98% uptime SLA"'],
+    authority: ['"Domain Authority 96"', '"2.5M monthly active users"'],
+    generic_platform: ['"Medium.com"', '"Reddit\'s r/entrepreneur"'],
+    generic_people: ['"Moz\'s 2024 study of 10,000 sites"', '"SEO expert Cody Schneider"'],
+    results: ['"+34% conversion rate"', '"10k → 50k monthly visitors"'],
+  };
+  return examples[category] || [];
+}
+
+function getRandomReplacement(category) {
+  const replacements = {
+    effectiveness: ['increases conversions by 34%', 'generates $200-500/month passive income', 'improves click-through rate by 28%'],
+    scale: ['2.5M active members', '500+ enterprise deployments', 'over 10,000 verified users'],
+    time: ['within 24-48 hours', 'in approximately 2 weeks', 'after 3 consecutive publish days'],
+    quality: ['ranked #1 for 15 target keywords', '98.5% average satisfaction score'],
+    authority: ['Domain Authority 96', '2.5M followers across platforms'],
+    generic_platform: ['Medium.com', 'LinkedIn', 'Twitter/X'],
+    generic_people: ['Moz 2024 study', 'Neil Patel analysis', 'HubSpot research'],
+    results: ['+34% conversion rate', '2.5x return on investment', '10,000 to 50,000 monthly visitors'],
+  };
+  const list = replacements[category] || ['specific, measurable result'];
+  return list[Math.floor(Math.random() * list.length)];
+}

package/skills/concreteness-fixer/utils/execFileNoThrow.js

@@ -0,0 +1,16 @@
+const { execFile } = require('child_process');
+
+async function execFileNoThrow(file, args, options = {}) {
+  return new Promise((resolve) => {
+    execFile(file, args, options, (error, stdout, stderr) => {
+      resolve({
+        stdout: stdout || '',
+        stderr: stderr || '',
+        error: error || null,
+        status: error ? (error.code || 1) : 0,
+      });
+    });
+  });
+}
+
+module.exports = { execFileNoThrow };

package/skills/content-atomizer/SKILL.md

@@ -0,0 +1,424 @@
+---
+name: content-atomizer
+description: "Take one piece of long-form content and atomize it into 10-20 platform-specific posts across 8 platforms (Twitter/X, LinkedIn, Instagram, Reddit,..."
+category: content
+tier: core
+reads:
+  - brand/voice-profile.md
+  - brand/audience.md
+writes:
+  - marketing/social/{source-slug}/
+depends-on:
+- brand-voice
+- hook-generator
+- sharp-thesis-validator
+triggers:
+  - repurpose
+  - atomize
+  - turn this into posts
+  - social content from
+  - content repurposing
+  - break this down
+  - social posts from blog
+  - distribute this
+allowed-tools: []
+---
+
+# Content Atomizer
+
+You take one piece of long-form content and extract 10-20 standalone social posts, each native to its target platform. Not lazy copy-paste with different character counts — genuine reformatting that makes each post feel like it was written platform-first.
+
+## On Activation
+
+1. **Awareness Gate (MANDATORY):** Determine the target audience's awareness level before any copy work. See `references/awareness-level-guide.md`. If unclear from context, ask the user.
+2. Read `brand/voice-profile.md` — maintain consistent voice across platforms
+3. Read `brand/audience.md` — know which platforms matter and how the audience behaves on each
+3. Load `references/platform-specs.md` for the quick reference table, then load individual platform files from `references/platforms/` as needed (linkedin.md, twitter.md, instagram.md, tiktok.md, youtube.md, threads.md, bluesky.md, reddit.md)
+4. Accept the source content (blog post, newsletter, video transcript, podcast transcript)
+5. If no source provided, check `marketing/content/` for recent articles
+
+### Zero Context (No Brand Files)
+
+If brand files don't exist, the skill still works:
+
+- **No voice-profile.md**: Write in a clear, professional default voice. Ask the user for 2-3 adjectives describing their brand tone.
+- **No audience.md**: Default to all platforms. Ask which platforms matter most to them.
+- The skill always works — brand files enhance, never gate.
+
+---
+
+## Brand Integration
+
+Brand files shape how content gets adapted per platform:
+
+- **voice-profile.md** → Each platform gets the same voice in different registers. Twitter gets punchy voice (short, sharp). LinkedIn gets authoritative voice (complete thoughts, data). Reddit gets authentic voice (conversational, no marketing speak). The voice DNA stays constant; the register shifts.
+- **audience.md** → Watering holes from the audience profile determine which platforms to prioritize. If your audience lives on Twitter and Reddit, don't waste time on Instagram carousels.
+
+**Funnel grounding (if `funnel_id` provided):**
+Read `funnels/{funnel_id}-*.md` from the brand's `funnels/` directory before atomizing.
+Every social post MUST include: `funnel_id`, `buyer_stage`, `cta`, `icp_segment`.
+Use the funnel's CTA — not a generic one. If a post's CTA doesn't match the funnel's conversion step, fix it.
+When no funnel_id is provided, proceed without funnel constraints.
+
+---
+
+## The Atomization Process
+
+### Phase 0: Sharp-Thesis Validation (MANDATORY — Social Mode)
+
+Before atomizing, validate the source content's core thesis passes the Sharp-Thesis Test:
+
+```
+sharp-thesis-validator --mode social --brand {brand} "{core thesis from source content}"
+```
+
+**On PASS:** Proceed to Step 1.
+**On FAIL:** 
+- If the source content itself was never thesis-validated (long-form), note the weakness
+- Extract only insights that CAN be framed as sharp theses
+- Do NOT atomize weak/generic insights — they produce weak/generic social posts
+- Each atomized post should individually pass the social-mode validator
+
+### Step 1: Extract Raw Material
+
+Read the source content and extract:
+
+- **Key insights**: 3-5 original ideas or arguments
+- **Quotable lines**: Sentences that stand alone as wisdom
+- **Stats/data points**: Any numbers, percentages, results
+- **Stories/anecdotes**: Narrative moments that create emotional connection
+- **Contrarian takes**: Opinions that challenge conventional wisdom
+- **Step-by-step processes**: Any how-to sequences
+- **Lists**: Any grouped items (tools, tips, mistakes, etc.)
+
+Tag each extraction with its type. This is your raw material inventory.
+
+### Step 2: Map to Platforms
+
+Each extraction type maps naturally to specific platforms and formats:
+
+| Extraction Type | Twitter/X | LinkedIn | Instagram | Reddit | TikTok | YouTube | Threads | Bluesky |
+|----------------|-----------|----------|-----------|--------|--------|---------|---------|---------|
+| Key insight | Single tweet | Text post | Carousel slide | Comment/post | Hot take (15s) | Short (30s) | Single post | Single post |
+| Quotable line | Quote tweet | Text post with context | Quote graphic caption | — | Green screen | — | Quote-post | Thoughtful take |
+| Stats/data | Data tweet | Data post with analysis | Infographic caption | Data post | Data reveal (20s) | Short (30s) | Mini-thread | Link post |
+| Story | Thread opener | Story post | Story caption | Long-form post | Story format (30-60s) | Long-form (8-12m) | Conversational post | Experience report |
+| Contrarian take | Hot take tweet | Debate post | — | Discussion post | Controversy spark (15s) | Short (15s) | Friendly disagreement | Informed take |
+| Step-by-step | Thread | Carousel/document | Carousel | How-to post | Tutorial (30-60s) | Long-form (8-12m) | Mini-thread | Thread |
+| List | Thread or single | Listicle post | Carousel | List post | Listicle (20s) | Short (45s) | Single post | Single post |
+
+Load the specific platform file from `references/platforms/` for full playbooks, algorithm signals, templates, and hook formulas.
+
+### Step 3: Write Platform-Native Posts
+
+---
+
+## Platform Rules
+
+### Twitter/X
+
+**Character limit**: 280 per tweet, threads unlimited
+
+**Single Tweet Formula:**
+```
+[Hook — pattern interrupt or bold claim]
+
+[1-2 sentences of value or proof]
+
+[CTA or takeaway]
+```
+
+**Thread Formula (Nicolas Cole Perfect Thread Structure):**
+```
+Tweet 1 (Lead): Hook — big promise or contrarian take + TLDR of the payoff
+Tweet 2 (Bridge): "Here's the context..." — sets up why this matters
+Tweet 3-N (Points): One idea per tweet, each must standalone, numbered when possible
+Tweet N+1 (TLDR): "TLDR:" — 1-2 sentence distillation of the entire thread
+Tweet N+2 (CTA): Summary + specific ask + "Follow for more [topic]"
+```
+
+**TLDR-First Technique:** Every thread must contain a TLDR tweet. Place it as the second-to-last tweet. Write it AFTER drafting all points, then compress the entire thread into 1-2 sentences. The TLDR serves readers who skim and gives retweeters a quotable summary.
+
+**Thread Opening Strategies (load `references/hook-strategies.md` for full detail):**
+1. **Controversial statement** — challenges a widely held belief
+2. **Secret knowledge** — "What nobody tells you about..."
+3. **The "I was wrong"** — vulnerability + lesson
+4. **Data drop** — shocking stat as the hook
+5. **Story opener** — "Last week I..." narrative hook
+6. **Direct challenge** — "Stop doing X. Do Y instead."
+
+**Thread Point Structures (load `references/tweet-patterns.md` for all 20 patterns):**
+- Numbered list threads: "5 things I learned..."
+- Myth-busting threads: "Everyone says X. They're wrong."
+- Playbook threads: "Here's the exact process..."
+- Story threads: chronological narrative with lessons
+- Resource threads: curated list of tools/tips
+
+**Rules:**
+- Hook tweet determines 90% of engagement — spend 50% of time on it
+- One idea per tweet in threads
+- Use line breaks for readability
+- No hashtags in the main text (one in reply if any)
+- End threads with a retweet ask or follow CTA
+- Optimal: 5-12 tweets per thread
+- ALWAYS include a TLDR tweet — never skip it
+
+**Hook patterns that work:**
+- "I spent [time] doing [thing]. Here's what I learned:"
+- "[Contrarian statement]. Here's why:"
+- "[Big number] [result] in [timeframe]. The playbook:"
+- "Stop doing [common thing]. Do this instead:"
+- "The [topic] advice nobody gives you:"
+
+### LinkedIn
+
+**Character limit**: 3,000 per post
+
+**Post Formula:**
+```
+[Hook line — stops the scroll]
+
+[Line break]
+
+[Story or context — 3-5 short paragraphs]
+
+[Key insight or lesson]
+
+[Call to engage: question, agree/disagree, share your experience]
+
+[3-5 hashtags at the bottom]
+```
+
+**Rules:**
+- First line is everything — it shows before "see more"
+- Write in short paragraphs (1-2 sentences each)
+- Use "I" — personal stories outperform corporate content 3x
+- End with a question to drive comments
+- 3-5 relevant hashtags at the bottom only
+- No links in the post body (kills reach) — put links in first comment
+- Document format/carousels get 3x reach over text posts
+- Optimal length: 800-1,500 characters
+
+**Hook patterns:**
+- "I made a mistake that cost me [consequence]."
+- "Unpopular opinion: [take]"
+- "After [X years/months] of [doing thing], here's what actually works:"
+- "[Achievement]. But it almost didn't happen."
+
+### Instagram
+
+**Character limit**: 2,200 per caption
+
+**Caption Formula:**
+```
+[Hook line — first 125 characters show in feed]
+
+[Value content — tips, story, insight]
+
+[CTA — save this, share with someone, comment your take]
+
+.
+.
+.
+[Hashtags — 5-15 relevant ones]
+```
+
+**Carousel Strategy:**
+- Slide 1: Bold headline (this is the hook)
+- Slides 2-N: One point per slide, large text, minimal design
+- Final slide: Summary + CTA + account tag
+- 7-10 slides is the sweet spot
+- Provide text content for each slide with design notes
+
+**Rules:**
+- First 125 characters = the hook (visible before "more")
+- Carousel posts get 1.4x more reach than single images
+- Include image/graphic brief with each post
+- Hashtags in caption or first comment (test both)
+- CTAs that work: "Save this for later" / "Tag someone who needs this"
+
+### Reddit
+
+**Rules are different here. Reddit hates marketing.**
+
+**Post Formula:**
+```
+Title: [Specific, descriptive, no clickbait]
+
+Body:
+[Context — who you are, why you're sharing]
+[The actual value — detailed, generous, no gatekeeping]
+[Results or proof if applicable]
+[Question to invite discussion]
+
+[NO self-promotion links in the body]
+```
+
+**Rules:**
+- Provide genuine value first, always
+- Match the subreddit's tone and norms
+- No links to your stuff in the post — put them in a comment if asked
+- Write longer, more detailed posts than other platforms
+- Be ready for skepticism — back up claims
+- Identify 2-3 relevant subreddits per topic
+- Title is plain and specific, not clickbaity
+
+---
+
+## Hooks and CTAs
+
+**Hook-generator integration:** For each platform's posts, spawn a hook-generator subagent with platform-specific context:
+```
+Load the hook-generator skill and execute the full Phase 1-6 pipeline with this context.
+Context:
+- WHO: <audience for this platform>
+- WHAT/WHY: <key insight from source content>
+- Knife: <pain point this atom addresses>
+- Platform: <twitter / instagram / linkedin / tiktok / youtube / medium — map per output platform>
+- Brand: <brand name>
+- Target Score: 85
+Return ONLY this JSON array: [{"hook":"...","score":<0-100>,"pattern":"...","formula":"..."}]
+```
+Use scored hooks as opening lines for each platform's post. Discard any that don't fit platform norms. If subagent fails, fall back to the Universal Hook Formulas below.
+
+### Universal Hook Formulas (fallback)
+
+1. **The Number**: "7 things I learned about [topic]"
+2. **The Mistake**: "The biggest [topic] mistake I see:"
+3. **The Contrarian**: "[Common belief] is wrong. Here's why:"
+4. **The Curiosity Gap**: "Most people [do X]. Top performers [do Y]."
+5. **The Story**: "Last week, something happened that changed how I think about [topic]."
+6. **The How-To**: "How to [achieve result] in [timeframe]:"
+7. **The Data**: "[Stat]. Here's what that means for you:"
+
+### CTA Types by Goal
+
+| Goal | CTA |
+|------|-----|
+| Engagement | "What's your take?" / "Agree or disagree?" |
+| Follows | "Follow for daily [topic] tips" |
+| Saves | "Save this for when you need it" |
+| Shares | "Tag someone who needs to hear this" |
+| Traffic | "Link in bio" / "Link in comments" |
+| Email capture | "I wrote a deeper guide — link in bio" |
+
+---
+
+## Output Structure
+
+For each source piece, output a directory:
+
+```
+marketing/social/{source-slug}/
+├── twitter-threads.md    # 2-3 threads with hook tweets
+├── twitter-singles.md    # 5-8 standalone tweets
+├── linkedin-posts.md     # 3-5 LinkedIn posts
+├── instagram-captions.md # 2-3 captions with carousel briefs
+├── reddit-posts.md       # 1-2 Reddit posts with subreddit targets
+├── tiktok-scripts.md     # 1-2 short video scripts (15-60s)
+├── youtube-shorts.md     # 1-2 YouTube Shorts scripts
+├── threads-posts.md      # 2-3 Threads posts or mini-threads
+└── bluesky-posts.md      # 2-3 Bluesky posts
+```
+
+Only generate files for platforms the user wants. If no preference stated, generate for all 8 platforms. If source content is short (under 500 words), reduce to 6-10 posts across fewer platforms rather than stretching thin.
+
+Each post includes:
+
+```yaml
+---
+platform: twitter | linkedin | instagram | reddit
+type: thread | single | post | carousel | story
+source: "original-content-slug"
+hook: "first line preview"
+character_count: 247
+hashtags: ["tag1", "tag2"]
+suggested_time: "Tuesday 9am ET"
+status: draft
+---
+```
+
+---
+
+## Posting Schedule
+
+| Platform | Best Times (ET) | Frequency |
+|----------|----------------|-----------|
+| Twitter/X | 8-10am, 12-1pm, 5-6pm | 1-3x daily |
+| LinkedIn | 8-10am Tue-Thu | 3-5x weekly |
+| Instagram | 11am-1pm, 7-9pm | 4-7x weekly |
+| Reddit | 6-9am, varies by sub | 2-3x weekly |
+| TikTok | 7-9pm Tue/Thu | 3-5x weekly |
+| YouTube Shorts | 9-11am Sat | 2-3x weekly |
+| Threads | 9-11am daily | 3-5x weekly |
+| Bluesky | 10am-12pm weekdays | 3-5x weekly |
+
+Space out atomized content over 1-2 weeks. Don't dump everything the same day.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| Copy-paste the same text across platforms | Platform algorithms detect duplicate content and suppress it. Users who follow you on multiple platforms see identical posts and feel spammed. Each platform has different character limits, norms, and audience expectations. | Rewrite natively for each platform's format and voice |
+| Reuse the same hook pattern in a batch | When 5 posts in a row start with "Here's what I learned:", the algorithm treats it as low-variety content and your audience scrolls past. Batch monotony is the #1 tell of AI-generated content. | Vary hook formulas — alternate numbers, stories, contrarian, question |
+| Atomize everything regardless of source length | A 300-word email stretched to 15 posts produces hollow filler. Each post needs a standalone insight — if the source doesn't have enough, the posts won't have enough. | Under 500 words → 6-10 posts max. Under 200 words → don't atomize |
+| Post all atomized content the same day | Followers see 8 posts from you in one feed scroll and either mute or unfollow. Algorithms also penalize velocity spikes from a single account. | Space over 1-2 weeks with variety in timing |
+| Ignore platform culture (marketing speak on Reddit, hashtag spam on Twitter) | Reddit moderators remove overt marketing. Twitter's algorithm deprioritizes hashtag-heavy tweets. Each platform's community has unwritten rules about tone and format. | Read the platform rules in this skill and adapt |
+| Over-hashtag | Twitter and LinkedIn algorithms now treat excessive hashtags as spam signals. On Reddit, hashtags don't exist. Only Instagram still rewards them, and even there the trend is toward fewer. | Twitter: 0-1. LinkedIn: 3-5 at bottom. Instagram: 5-15. Reddit: 0 |
+
+---
+
+## Related Skills
+
+- **brand-voice**: Establish voice before atomizing at scale
+- **seo-content**: Create the source content to atomize
+- **newsletter**: Atomize newsletter content for social
+- **creative**: Generate visual asset briefs for social graphics
+
+---
+
+## STEP N: Copywriting Tournament (RECOMMENDED for social post hooks)
+
+Generate 3-5 variants of the key social post hooks, then run them through 5 parallel judge personas to find the winner:
+
+1. Generate 3-5 variants (different angles, formulas, or approaches)
+2. Save each to: `content/tournaments/{slug}/variant-1.md` through `variant-N.md`
+3. Spawn 5 PARALLEL `build` subagents (one per judge persona):
+   - `~/.claude/skills/quality-gate/judge-personas/skeptic.md`
+   - `~/.claude/skills/quality-gate/judge-personas/scanner.md`
+   - `~/.claude/skills/quality-gate/judge-personas/buyer.md`
+   - `~/.claude/skills/quality-gate/judge-personas/expert.md`
+   - `~/.claude/skills/quality-gate/judge-personas/outsider.md`
+   - Each gets: tournament_dir, variant_count, mode=`social`, original_prompt
+4. Collect all 5 JSON results, aggregate: sum weighted_avg per variant across judges
+5. Pick winner, apply recommended_edits, save as draft
+6. Winner enters standard quality-gate below
+
+**When to use:** For the first line of each atomized social post
+
+---
+
+## FINAL STEP: Quality Gate (MANDATORY — DO NOT SKIP)
+
+Before presenting ANY draft to Jairo, run the quality gate:
+
+1. Save your complete draft to a file (e.g., `content/drafts/{slug}.md` or a temp file)
+2. Spawn a `build` subagent using the Task tool with the quality-gate prompt from `Skill: quality-gate`
+3. Pass these inputs to the subagent:
+   - **draft_path**: absolute path to the saved draft
+   - **mode**: `social`
+   - **original_prompt**: the writing prompt that started this task
+   - **attempt**: current attempt number (start at 1)
+4. Parse the JSON result from the subagent
+5. If FAIL and attempt < 3:
+   - Rewrite the draft addressing the specific `rewrite_instructions` from the quality gate
+   - Save the new draft (overwrite or new file)
+   - Spawn another subagent with attempt + 1
+6. If FAIL and attempt = 3:
+   - Present to Jairo with all score reports attached
+   - Say: "Couldn't pass quality gate after 3 attempts. Here's what's wrong and what I tried to fix."
+7. If PASS:
+   - Present to Jairo as normal (do NOT show scores — they're internal)
+8. NEVER present a draft that hasn't passed quality gate (except after 3 failed attempts)