@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/brand-kit-playground/references/html-architecture.md

@@ -0,0 +1,316 @@
+# HTML Architecture Reference
+
+This document defines the structure of the generated `brand-playground.html` file. The agent uses this as a blueprint — not a copy-paste template. Every playground is bespoke to the brand.
+
+## Document Structure
+
+```html
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>[Brand Name] Brand Playground</title>
+  <!-- Google Fonts — constructed from brand tokens -->
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...">
+  <style>
+    /* 1. CSS Reset (minimal) */
+    /* 2. CSS Custom Properties on :root (brand tokens) */
+    /* 3. Dark/light theme variants via [data-theme] */
+    /* 4. Layout grid */
+    /* 5. Controls panel styles */
+    /* 6. Preview canvas styles */
+    /* 7. Social card renderer styles */
+    /* 8. Multi-preview strip styles */
+    /* 9. Token output styles */
+    /* 10. Governance strip styles */
+  </style>
+</head>
+<body>
+  <!-- Brand bar -->
+  <!-- Main grid: controls | preview -->
+  <!-- Token output -->
+  <script>
+    /* 1. State object */
+    /* 2. DOM references */
+    /* 3. updateAll() — master render function */
+    /* 4. renderBrandSystem() */
+    /* 5. renderSocialCard() */
+    /* 6. renderOGImage() */
+    /* 7. renderMultiPreview() */
+    /* 8. runGovernance() */
+    /* 9. updateTokenOutput() */
+    /* 10. Control event listeners */
+    /* 11. Tab switching */
+    /* 12. Preset loader */
+    /* 13. Copy to clipboard */
+    /* 14. Theme toggle */
+    /* 15. Init */
+  </script>
+</body>
+</html>
+```
+
+## CSS Custom Properties
+
+All brand tokens are CSS custom properties on `:root`. Controls modify these directly via `document.documentElement.style.setProperty()`.
+
+```css
+:root {
+  /* Brand colors */
+  --brand-primary: #6366F1;
+  --brand-primary-fg: #FFFFFF;
+  --brand-secondary: #7C3AED;
+  --brand-secondary-fg: #FFFFFF;
+  --brand-accent: #F59E0B;
+  --brand-accent-fg: #1C1917;
+  --brand-bg: #FFFFFF;
+  --brand-fg: #0F172A;
+  --brand-muted: #F1F5F9;
+  --brand-muted-fg: #64748B;
+
+  /* Typography */
+  --brand-font-display: 'Space Grotesk', system-ui, sans-serif;
+  --brand-font-body: 'Inter', system-ui, sans-serif;
+  --brand-font-mono: 'JetBrains Mono', ui-monospace, monospace;
+  --brand-type-base: 16px;
+  --brand-type-ratio: 1.25;
+
+  /* Visual */
+  --brand-radius: 8px;
+  --brand-shadow: 0 4px 6px -1px rgba(0,0,0,0.1);
+
+  /* Playground chrome (derived from brand) */
+  --chrome-bg: #0F172A;
+  --chrome-surface: #1E293B;
+  --chrome-border: #334155;
+  --chrome-text: #E2E8F0;
+  --chrome-text-muted: #94A3B8;
+}
+```
+
+## State Management
+
+Single state object. Every control writes to it. Every render reads from it.
+
+```javascript
+const state = {
+  tab: 'brand',           // 'brand' | 'social' | 'og'
+  theme: 'dark',          // 'dark' | 'light'
+
+  tokens: {
+    colors: {
+      primary: '#6366F1',
+      primaryForeground: '#FFFFFF',
+      secondary: '#7C3AED',
+      accent: '#F59E0B',
+      background: '#FFFFFF',
+      foreground: '#0F172A',
+    },
+    typography: {
+      display: { family: 'Space Grotesk', weights: [700, 800] },
+      body: { family: 'Inter', weights: [400, 500, 600] },
+      scale: { base: 16, ratio: 1.25 },
+    },
+    visual: {
+      borderRadius: 8,
+      shadowDepth: 'md',
+      texture: 'none',
+    },
+  },
+
+  social: {
+    headline: 'We just shipped dark mode',
+    subhead: 'Available for all users today',
+    badge: 'NEW',
+    layout: 'centered',    // 'centered' | 'split' | 'overlay' | 'minimal'
+    background: 'gradient', // 'gradient' | 'solid' | 'dark' | 'light'
+    showLogo: true,
+  },
+
+  og: {
+    title: 'Building the future of developer tools',
+    description: 'A deep dive into our latest release.',
+    author: '',
+    tag: 'Engineering',
+    layout: 'editorial',   // 'editorial' | 'minimal' | 'bold'
+  },
+};
+
+function updateAll() {
+  updateCSSVars();
+  renderActiveTab();
+  runGovernance();
+  updateTokenOutput();
+}
+```
+
+## Social Card Renderer
+
+The social card is rendered inside a fixed-aspect-ratio container using the `aspect-ratio` CSS property. The main preview shows the card at the selected platform size, scaled to fit the canvas via `transform: scale()`.
+
+```javascript
+function renderSocialCard() {
+  const card = document.getElementById('social-card-preview');
+  const { headline, subhead, badge, layout, background, showLogo } = state.social;
+  const { colors, typography, visual } = state.tokens;
+
+  // Set dimensions based on current target (default: Twitter 1200x675)
+  card.style.width = '1200px';
+  card.style.height = '675px';
+
+  // Background styles
+  switch (background) {
+    case 'gradient':
+      card.style.background = `linear-gradient(135deg, ${colors.primary}, ${colors.secondary})`;
+      card.style.color = colors.primaryForeground;
+      break;
+    case 'solid':
+      card.style.background = colors.primary;
+      card.style.color = colors.primaryForeground;
+      break;
+    case 'dark':
+      card.style.background = '#0F172A';
+      card.style.color = '#F8FAFC';
+      break;
+    case 'light':
+      card.style.background = colors.background;
+      card.style.color = colors.foreground;
+      break;
+  }
+
+  // Layout variants
+  // ... (agent writes layout-specific positioning)
+
+  // Scale to fit canvas
+  const canvas = document.getElementById('canvas');
+  const scale = Math.min(
+    canvas.clientWidth / 1200,
+    canvas.clientHeight / 675
+  );
+  card.style.transform = `scale(${scale})`;
+  card.style.transformOrigin = 'top left';
+}
+```
+
+## Multi-Preview Strip
+
+Below the main canvas, render the same social card at all target sizes simultaneously, scaled down to thumbnails:
+
+```javascript
+const SOCIAL_TARGETS = [
+  { name: 'Twitter/X', w: 1200, h: 675 },
+  { name: 'LinkedIn', w: 1200, h: 627 },
+  { name: 'Instagram', w: 1080, h: 1080 },
+  { name: 'Story', w: 1080, h: 1920 },
+];
+
+function renderMultiPreview() {
+  const strip = document.getElementById('multi-preview');
+  strip.innerHTML = '';
+  for (const target of SOCIAL_TARGETS) {
+    const thumb = createSocialCardClone(target.w, target.h);
+    const scale = 80 / target.h; // 80px tall thumbnails
+    thumb.style.transform = `scale(${scale})`;
+    thumb.style.transformOrigin = 'top left';
+    // Wrap in container sized to scaled dimensions
+    const wrapper = document.createElement('div');
+    wrapper.style.width = `${target.w * scale}px`;
+    wrapper.style.height = '80px';
+    wrapper.style.overflow = 'hidden';
+    wrapper.appendChild(thumb);
+    strip.appendChild(wrapper);
+  }
+}
+```
+
+## Governance Implementation
+
+Inline WCAG contrast ratio check — no library:
+
+```javascript
+function relativeLuminance(hex) {
+  const r = parseInt(hex.slice(1,3), 16) / 255;
+  const g = parseInt(hex.slice(3,5), 16) / 255;
+  const b = parseInt(hex.slice(5,7), 16) / 255;
+  const [R, G, B] = [r, g, b].map(c =>
+    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+  );
+  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+}
+
+function contrastRatio(hex1, hex2) {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function runGovernance() {
+  const checks = [];
+  const { colors } = state.tokens;
+
+  // Primary on background
+  const ratio = contrastRatio(colors.primary, colors.background);
+  checks.push({
+    label: 'Primary/BG',
+    ratio: ratio.toFixed(1),
+    pass: ratio >= 4.5,
+    level: ratio >= 7 ? 'AAA' : ratio >= 4.5 ? 'AA' : 'Fail',
+  });
+
+  // Foreground on background
+  const fgRatio = contrastRatio(colors.foreground, colors.background);
+  checks.push({
+    label: 'Text/BG',
+    ratio: fgRatio.toFixed(1),
+    pass: fgRatio >= 4.5,
+    level: fgRatio >= 7 ? 'AAA' : fgRatio >= 4.5 ? 'AA' : 'Fail',
+  });
+
+  // Render governance strip
+  const strip = document.getElementById('governance');
+  strip.innerHTML = checks.map(c =>
+    `<span class="gov-check ${c.pass ? 'pass' : 'fail'}">
+      ${c.pass ? '\u2713' : '\u26a0'} ${c.label}: ${c.level} (${c.ratio}:1)
+    </span>`
+  ).join('');
+}
+```
+
+## Theme Toggle
+
+The playground chrome defaults to dark. Toggle switches `data-theme` on `<html>`:
+
+```javascript
+function toggleTheme() {
+  const html = document.documentElement;
+  const next = html.dataset.theme === 'dark' ? 'light' : 'dark';
+  html.dataset.theme = next;
+  state.theme = next;
+}
+```
+
+Dark theme uses the brand's dark palette for chrome. Light theme uses the brand's light palette. The preview canvas always shows the asset as it would appear — independent of the playground theme.
+
+## Copy to Clipboard
+
+```javascript
+async function copyTokens() {
+  const json = JSON.stringify(state.tokens, null, 2);
+  await navigator.clipboard.writeText(json);
+  const btn = document.getElementById('copy-btn');
+  btn.textContent = 'Copied!';
+  setTimeout(() => btn.textContent = 'Copy Tokens', 1500);
+}
+```
+
+## Responsive Behavior
+
+The playground is designed for desktop screens (1200px+). On smaller screens:
+- Controls panel collapses to a bottom drawer
+- Preview takes full width
+- Multi-preview strip scrolls horizontally
+
+Do not over-engineer responsiveness. This is a local dev tool opened on the developer's workstation.

package/skills/brand-kit-playground/references/steal-patterns.md

@@ -0,0 +1,88 @@
+# Patterns to Steal for v3
+
+## From a polished review workspace
+
+### Global Color Transition (No Layout Jank)
+```css
+* {
+  transition-property: color, background-color, border-color, box-shadow;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+  transition-duration: 150ms;
+}
+```
+Excludes `transform` and `opacity` to avoid scroll compositing issues.
+
+### oklch Glow Effects
+```css
+.glow-primary {
+  box-shadow: 0 0 20px oklch(from var(--primary) l c h / 0.15),
+              0 0 40px oklch(from var(--primary) l c h / 0.05);
+}
+```
+Derives opacity variants from the same brand hue automatically.
+
+### Subtle Grid Background
+```css
+.bg-grid {
+  background-image:
+    linear-gradient(to right, oklch(0.32 0.02 260 / 0.5) 1px, transparent 1px),
+    linear-gradient(to bottom, oklch(0.32 0.02 260 / 0.5) 1px, transparent 1px);
+  background-size: 24px 24px;
+}
+```
+
+### Double-Pulse Flash (Better Than Fade)
+```css
+@keyframes state-flash {
+  0% { background: transparent; }
+  10% { background: var(--muted); }
+  30% { background: transparent; }
+  45% { background: var(--muted); }
+  100% { background: transparent; }
+}
+```
+
+### Custom Scrollbar
+```css
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: var(--muted-foreground); }
+```
+
+### Color Swatch Grid Preset Picker
+5 color dots (w-3 h-3 rounded-full) per preset row. Selected state: border-primary + bg-primary/5.
+
+### Resizable Panel (~80 lines)
+- `pointerdown/pointermove/pointerup` (unified mouse+touch)
+- 3px drag threshold
+- `getBoundingClientRect()` on start (works regardless of CSS transforms)
+- Min/max clamp + localStorage persistence
+
+## From App Store Screenshots Skill
+
+### Resolution-Independent Typography
+```
+headline: W * 0.09-0.10, weight 700, lineHeight 0.92-1.0
+category: W * 0.028, weight 600
+```
+All sizes derive from canvas width — adapts to any resolution.
+
+### CSS-Only Device Frame
+```css
+background: linear-gradient(180deg, #2C2C2E 0%, #1C1C1E 100%);
+box-shadow: inset 0 0 0 1px rgba(255,255,255,0.1), 0 8px 40px rgba(0,0,0,0.6);
+border-radius: 18px;
+```
+Front camera dot, bezel highlight, screen area with overflow hidden.
+
+### Floating Decorative Elements
+- Slight 2-5deg rotation
+- Drop shadows
+- Position at card edges
+- Never blocking main content
+
+### Preview vs Export Architecture
+- Preview: `transform: scale()` via ResizeObserver
+- Export: offscreen at true resolution (`position: absolute; left: -9999px`)
+- Double-call html-to-image trick (first warms fonts, second produces clean output)

package/skills/brand-voice/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: brand-voice
+description: "Define or extract a consistent brand voice that other skills can use. Three modes: Extract (analyze existing content), Build (interview-based),..."
+category: foundation
+tier: must-have
+reads:
+  - brand/positioning.md
+  - brand/audience.md
+writes:
+  - brand/voice-profile.md
+triggers:
+  - what's my voice
+  - analyze my brand
+  - define my voice
+  - make this sound like me
+  - voice guide
+  - brand personality
+  - analyze my website
+  - brand voice
+---
+
+# /brand-voice -- Brand Voice Engine
+
+Generic copy converts worse than copy with a distinct voice. Not because the
+words are different -- because the reader feels like they're hearing from a
+PERSON, not a marketing team.
+
+This skill defines that voice. Either by extracting it from existing content,
+building it strategically from scratch, or auto-scraping a URL to analyze a
+brand's public presence.
+
+For output formatting, see /cmo [rules/output-format.md](../cmo/rules/output-format.md).
+
+---
+
+## On Activation
+
+1. Read `brand/` context:
+   - **positioning.md** — If available, use market angles to inform voice differentiation. A brand positioned as "the anti-course course" needs a different voice than one positioned as "enterprise-grade."
+   - **audience.md** — If available, tailor vocabulary and tone to the target reader. Technical builders get different language than busy executives.
+   - If neither exists, proceed with defaults. Ask the user about their market and audience during the question sequence.
+2. Check if `./brand/voice-profile.md` already exists:
+   - **Exists** → Update mode: show current profile summary, ask what to change.
+   - **Does not exist** → Proceed to Mode Selection below.
+3. Assess the user's request to determine which mode to use (Extract, Build, or Auto-Scrape).
+
+## Three Modes
+
+### Mode 1: Extract (analyze existing content)
+
+User provides 3-5 pieces of existing content (blog posts, emails, social posts, about page, etc).
+
+**The analysis process:**
+
+1. **Read all provided content** -- look for patterns, not individual word choices
+2. **Identify the voice DNA:**
+   - Sentence structure (short/punchy vs. flowing/complex)
+   - Vocabulary level (everyday vs. technical vs. academic)
+   - Emotional register (warm/friendly vs. authoritative vs. irreverent)
+   - Perspective (first-person storytelling vs. objective analysis)
+   - Rhythm (varies sentence length? staccato? musical?)
+3. **Map the personality axes** (see Voice DNA Framework below)
+4. **Generate the voice profile**
+5. **Write to ./brand/voice-profile.md**
+
+### Mode 2: Build (construct from scratch)
+
+No existing content. Build voice strategically through guided questions.
+
+**The question sequence:**
+
+1. "If your brand were a person at a dinner party, how would they talk?"
+2. "Who is your audience? Technical builders, creative professionals, busy executives, everyday consumers, or a mix?"
+3. "Name 2-3 brands whose tone you admire (not their product -- their VOICE)."
+4. "What words should NEVER appear in your marketing? What feels off-brand?"
+5. "Show me something you've written that felt 'right' -- even a Slack message or email."
+
+### Mode 3: Auto-Scrape (URL analysis)
+
+User provides a URL. Skill uses Exa MCP to research the brand's public presence.
+
+1. Use Exa MCP to search for the brand's website content, social profiles, and public-facing copy
+2. Analyze homepage, about page, social bios, recent posts
+3. Extract voice patterns using the same DNA framework as Mode 1
+4. Present findings and ask user to confirm/adjust
+5. Generate voice profile
+
+## Mode Selection
+
+Not sure which mode? Here's the decision tree:
+- **Have 3+ pieces of existing content** (blog posts, emails, landing pages) → Mode 1: Extract
+- **Starting fresh with no content** → Mode 2: Build via interview
+- **Have a live website URL** → Mode 3: Auto-Scrape
+
+If the brand has both a website AND existing content, prefer Mode 1 (Extract) — it captures the voice the brand already uses, which is more authentic than what a URL scan reveals.
+
+---
+
+## Voice DNA Framework
+
+Every voice maps across these axes:
+
+### Personality Spectrum
+
+Rate each 1-10 with brief justification:
+- Formal / Casual
+- Reserved / Expressive
+- Serious / Playful
+- Traditional / Progressive
+- Complex / Simple
+- Cautious / Bold
+
+### Voice Markers
+
+**Sentence patterns:** Average length, variation, structure (simple/compound/fragmented)
+
+**Vocabulary:** Jargon level (none/light/technical), power words, forbidden words
+
+**Perspective:** Person (I/we/you), distance (intimate/conversational/professional), authority (peer/mentor/expert/challenger)
+
+### The Do/Don't Table
+
+Minimum 5 rows, maximum 10. Specific voice behaviors and example phrases.
+
+### Platform Adaptation Table
+
+| Platform | Tone Shift | Length | Special Notes |
+|----------|-----------|--------|--------------|
+| LinkedIn | More professional, authority-forward | Medium | Lead with insight |
+| Twitter/X | Punchier, more direct | Short | Fragment sentences OK |
+| Instagram | Warmer, more visual language | Short-Medium | Casual, aspirational |
+| Email | Most personal, conversational | Medium-Long | First-person storytelling |
+| Blog/SEO | Most detailed, structured | Long | Can be more technical |
+| TikTok | Most casual, spoken-word feel | Very short | Conversational, raw |
+| Threads | Thoughtful, conversational | Short-Medium | Opinion-led |
+| Bluesky | Nuanced, substantive | Short | Informed, not aggressive |
+
+---
+
+## Output Format
+
+### Header
+
+```
+  BRAND VOICE PROFILE
+  [Brand/Person Name]
+  Generated [Month Day, Year]
+```
+
+### Content
+
+1. **Voice Summary** (2-3 sentences capturing the essence)
+2. **Personality Spectrum** (rated axes)
+3. **Voice Markers** (sentence patterns, vocabulary, perspective)
+4. **The Do/Don't Table**
+5. **Platform Adaptation Table**
+6. **Sample Copy** (3 examples: short social post, email opener, landing page headline)
+
+### Files Saved
+
+Write to `./brand/voice-profile.md`.
+
+### What's Next
+
+```
+  -> /positioning-angles   Find your market angle
+  -> /direct-response-copy Write copy in your voice
+  -> /content-atomizer     Create social content
+```
+
+---
+
+## File Output Protocol
+
+Write ./brand/voice-profile.md with: last updated, voice summary, personality spectrum, voice markers, do/don't table, platform adaptations, sample copy.
+
+**If ./brand/voice-profile.md already exists:** Read existing file, show what will change, ask for confirmation before overwriting.
+
+---
+
+## Feedback
+
+After the voice profile is saved and used in at least one downstream skill, collect feedback:
+- "How did the voice feel in that [email/post/page]? (a) Nailed it, (b) Close but edited, (c) Off, (d) Haven't used yet"
+- For (a) or (b): append what worked to `brand/learnings.md` with date and skill name.
+- For (c): ask what felt wrong, adjust the voice profile, and log the change to `brand/learnings.md`.
+
+
+## Voice Test Loop (Required)
+
+After generating a voice profile from ANY mode, validate before saving. Full details in [references/voice-modes.md](references/voice-modes.md).
+
+1. Generate 3 sample paragraphs in the brand's voice: email opening, social post, landing page hero.
+2. Present with options: (1) Nails it → save, (2) Close but needs adjustment → ask what's off, revise, re-test, (3) Not quite right → ask for examples, rebuild relevant sections, re-test.
+3. After 3 rounds without confirmation, offer: save current version, one more round, or restart with a different mode.
+
+Never skip this step. Never save a profile without user confirmation.
+
+## Anti-Patterns
+
+| Anti-pattern | Instead | Why |
+|-------------|---------|-----|
+| Generating a generic "professional yet approachable" voice | Extract specific patterns from real content or deep questioning | Generic profiles are useless — every downstream skill produces the same bland output. The whole point is differentiation. |
+| Skipping the Voice Test Loop | Always validate with 3 samples before saving | A profile that looks right on paper can sound wrong in practice. The test loop catches mismatches before they propagate to all other skills. |
+| Copy-pasting platform adaptation template defaults | Each brand has different platform behaviors — think about each one | A casual brand might be MORE formal on LinkedIn. A formal brand might loosen up on Twitter. Defaults are wrong by definition. |
+| Writing the profile without reading existing brand context | Check positioning.md and audience.md first | Voice should align with positioning and audience. Writing voice in isolation means rewriting it later when those files exist. |
+| Overwriting an existing profile without showing diff | Read existing file, show what will change, get confirmation | The user may have manually tweaked the profile. Blindly overwriting loses their refinements. |
+| Producing a profile with no example phrases | On-brand and off-brand examples are required | Examples are the fastest way for downstream skills to calibrate. Without them, other skills have to interpret abstract axes, which leads to drift. |
+
+## Invocation
+
+This skill activates when:
+- User asks "what's my voice" or "analyze my brand"
+- User says copy sounds "generic" or "off-brand"
+- Another skill needs voice context but ./brand/voice-profile.md doesn't exist
+- User provides a URL and asks to analyze the brand
+
+## What This Skill Is NOT
+
+- Does NOT write copy (that is /direct-response-copy)
+- Does NOT define positioning (that is /positioning-angles)
+- Does NOT research the audience (that is /audience-research)
+- Does NOT create visual identity (that is /creative)

package/skills/brand-voice/references/honesty-as-positioning.md

@@ -0,0 +1,60 @@
+# Honesty as a Positioning Lever
+
+Most brand voice work treats honesty as a tone modifier — "be transparent," "no buzzwords." That undersells it. **Honesty is a positioning lever.** When a brand publishes a tradeoff where a competitor wins, three things happen:
+
+1. The reader's skepticism filter drops. Vendor-published comparisons are presumed biased; conceding the obvious removes that assumption.
+2. The wins land harder. "We're better at X, Y, Z" reads as marketing copy. "They're better at A, B, C; we're better at X, Y, Z" reads as honest analysis.
+3. AI engines cite it. Perplexity, ChatGPT, Google AI Overviews preferentially cite sources that show "thinking" — pages that hedge every claim ("it depends") and pages that claim total superiority both get skipped. The honest middle gets cited.
+
+This reference doc lives in `skills/brand-voice/references/` because **honesty is a voice rule, not an SEO rule**. It applies to alternatives pages, landing-page heroes, cold emails, lead magnets, founder bios, and About pages. Any surface where a buyer is evaluating whether to trust the brand benefits from this discipline.
+
+## Where to apply
+
+| Surface | Honesty move | What it earns |
+|---|---|---|
+| `/alternatives/[competitor]` | "Choose [competitor] if:" section with 3 concrete tradeoffs where they win | Trust + AI-citation eligibility + conversion (reader feels seen, not sold) |
+| Landing-page hero | "Not for [persona X]. Built for [persona Y]." | Higher conversion among the right persona (lower among the wrong one — desirable filtering) |
+| Cold email | "We probably aren't the right fit if [scenario]." | Reply rate 2-3× vs generic "we help everyone" framing |
+| Pricing page | "Why we cost more than [competitor]" or "Why we're cheaper than [competitor]" | Pre-empts objection; shows the brand has thought about its own pricing |
+| Founder bio / About | "We started this because [we got burned by X]" | Authenticity signal; reader believes the brand has skin in the game |
+| Lead magnet pitch | "Don't download this if [scenario where it won't help]" | Higher download-to-conversion rate (only the right audience downloads) |
+| Comparison emails to sales prospects | "Here's what we don't do well yet" | Prospect trusts the rep more; deal cycle shortens |
+
+## The 3-tradeoff rule
+
+When applied to comparison content (`/alternatives` pages, `/compare` pages, sales decks), the honesty section MUST contain **at least 3 concrete tradeoffs** where the competitor wins:
+
+1. **Concrete** — names a specific feature, price point, integration, or scenario. Not "their UI is more polished" (vague). Yes "they support SSO on the $X/mo plan; we don't" (specific, verifiable).
+2. **Real** — actually true. Don't manufacture weakness to look humble; readers and AI engines both detect performative honesty.
+3. **Relevant to the buyer's decision** — the tradeoff has to matter to someone reading the page. "They have better office furniture" is honest but irrelevant.
+
+Fewer than 3 tradeoffs feels token. More than 5 starts to make your product look bad. Three is the sweet spot.
+
+## Anti-patterns
+
+- **Performative honesty.** "Honestly, our brand voice could use work." Empty admission with no concrete cost. Reads as fishing for compliments.
+- **Strawman tradeoffs.** "They have a flashier website but we focus on real value." That's a non-tradeoff dressed up as humility.
+- **Backhanded compliments.** "[Competitor] is great if you have a huge budget." Snark masquerading as honesty.
+- **Hedging-everything.** "Both products have strengths, it really depends on your use case, you should evaluate carefully…" — refusing to take a stance is the opposite of honesty.
+- **Honesty without a path forward.** Naming a weakness without explaining what the brand does instead or why it's a fair tradeoff = self-sabotage. Always pair "we don't do X" with "because we focus on Y, which matters more if you're Z."
+
+## Sourcing real tradeoffs
+
+Where to find competitor wins worth conceding:
+
+| Source | What you'll find |
+|---|---|
+| G2 / Capterra reviews of YOUR product | Look at the 3-star reviews — what do users say they miss? |
+| G2 / Capterra reviews of COMPETITOR | What do competitor users praise? Those are real strengths. |
+| Reddit threads comparing the two | Unfiltered opinions; ignore the noise but the recurring complaints are signal |
+| Churn-reason interviews | Why customers left for the competitor — the most expensive data, the most accurate |
+| Sales call recordings | Where your reps lose deals — the objection you can't overcome is the tradeoff worth conceding |
+| Internal "what they do better" doc | Most product teams have one; ask product or eng |
+
+If a tradeoff can't be sourced from one of the above, mark it `"unverified — needs evidence"` rather than ship a fabricated one.
+
+## Cross-references
+
+- `skills/competitor-alternatives/SKILL.md` — applies this rule to every `/alternatives` page as a required section
+- `skills/seo-machine/references/patterns/alternatives.md` — Pattern A quality bar enforces the 3-tradeoff minimum
+- `brand/SCHEMA.md` — `positioning.md > ## Anti-Positioning` is the upstream source: who the brand is NOT for. The anti-positioning slot feeds every honesty section downstream.