From 0def09076b5fef08d6e82dbe6d574538cddbeb26 Mon Sep 17 00:00:00 2001 From: testuser Date: Mon, 30 Mar 2026 00:36:08 -0400 Subject: [PATCH 01/18] =?UTF-8?q?feat:=20integrate=20marketing=20skills=20?= =?UTF-8?q?=E2=80=94=20copywriting,=20psychology,=20pricing,=20launches,?= =?UTF-8?q?=20paid=20ads,=20referrals,=20cold=20email?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New standalone skills: copywriting (absorbs ad-copy), marketing-psychology, pricing-strategy, launch-strategy, paid-ads, referral-program, cold-email, product-marketing-context. Enrichments: growth (CRO frameworks), seo-research (site architecture, audit format), churn-prevention (Chargebee Retention), content-strategy (social content, free tools, lead magnets, marketing ideas, blog SEO), evaluate-content (plain English alternatives). Deletes ad-copy (content preserved in copywriting). Supersedes #41 (clean rebase from main) --- README.md | 125 +--- ad-copy/SKILL.md | 51 -- churn-prevention/SKILL.md | 3 +- cold-email/SKILL.md | 121 ++++ content-strategy/SKILL.md | 188 +++++- .../references/blog-seo-planning.md | 153 +++++ .../references/free-tool-strategy.md | 113 ++++ content-strategy/references/lead-magnets.md | 126 ++++ .../references/marketing-ideas.md | 233 +++++++ content-strategy/references/social-content.md | 168 ++++++ copywriting/SKILL.md | 207 +++++++ .../references/1-app-store-descriptions.md | 192 ++++++ copywriting/references/2-google-ads.md | 144 +++++ copywriting/references/3-landing-pages.md | 152 +++++ .../references/4-tiktok-meta-ad-scripts.md | 231 +++++++ .../references/5-push-notifications.md | 76 +++ copywriting/references/6-email-sequences.md | 253 ++++++++ .../references/7-ugc-script-templates.md | 195 ++++++ .../references/a-b-testing-framework.md | 87 +++ .../references/brand-voice-reference.md | 27 + .../copy-anti-patterns-kill-on-sight.md | 66 ++ copywriting/references/copy-frameworks.md | 344 +++++++++++ .../references/direct-response-frameworks.md | 568 ++++++++++++++++++ .../references/direct-response-principles.md | 116 ++++ .../references/lead-magnet-patterns.md | 276 +++++++++ copywriting/references/natural-transitions.md | 272 +++++++++ .../platform-character-limits-reference.md | 74 +++ .../process-writing-copy-with-this-skill.md | 13 + .../references/quick-reference-cta-library.md | 18 + copywriting/references/quiz-funnel-copy.md | 67 +++ ...l-world-examples-finance-investing-apps.md | 61 ++ copywriting/references/references.md | 7 + copywriting/references/skill-integration.md | 7 + .../test-app-store-screenshot-order.md | 12 + ...the-seven-sweeps-copy-editing-framework.md | 19 + copywriting/references/writing_styles.md | 233 +++++++ email-sequence/SKILL.md | 2 +- email-sequence/references/copy-guidelines.md | 72 +-- evaluate-content/SKILL.md | 64 +- growth/SKILL.md | 21 +- growth/references/cro-frameworks.md | 385 ++++++++++++ launch-strategy/SKILL.md | 136 +++++ marketing-psychology/SKILL.md | 166 +++++ meta-ads/SKILL.md | 4 +- paid-ads/SKILL.md | 199 ++++++ pricing-strategy/SKILL.md | 161 +++++ product-marketing-context/SKILL.md | 173 ++++++ referral-program/SKILL.md | 131 ++++ seo-research/SKILL.md | 6 +- seo-research/references/ai-seo.md | 2 +- seo-research/references/seo-technical.md | 57 ++ seo-research/references/site-architecture.md | 163 +++++ 52 files changed, 6527 insertions(+), 213 deletions(-) delete mode 100644 ad-copy/SKILL.md create mode 100644 cold-email/SKILL.md create mode 100644 content-strategy/references/blog-seo-planning.md create mode 100644 content-strategy/references/free-tool-strategy.md create mode 100644 content-strategy/references/lead-magnets.md create mode 100644 content-strategy/references/marketing-ideas.md create mode 100644 content-strategy/references/social-content.md create mode 100644 copywriting/SKILL.md create mode 100644 copywriting/references/1-app-store-descriptions.md create mode 100644 copywriting/references/2-google-ads.md create mode 100644 copywriting/references/3-landing-pages.md create mode 100644 copywriting/references/4-tiktok-meta-ad-scripts.md create mode 100644 copywriting/references/5-push-notifications.md create mode 100644 copywriting/references/6-email-sequences.md create mode 100644 copywriting/references/7-ugc-script-templates.md create mode 100644 copywriting/references/a-b-testing-framework.md create mode 100644 copywriting/references/brand-voice-reference.md create mode 100644 copywriting/references/copy-anti-patterns-kill-on-sight.md create mode 100644 copywriting/references/copy-frameworks.md create mode 100644 copywriting/references/direct-response-frameworks.md create mode 100644 copywriting/references/direct-response-principles.md create mode 100644 copywriting/references/lead-magnet-patterns.md create mode 100644 copywriting/references/natural-transitions.md create mode 100644 copywriting/references/platform-character-limits-reference.md create mode 100644 copywriting/references/process-writing-copy-with-this-skill.md create mode 100644 copywriting/references/quick-reference-cta-library.md create mode 100644 copywriting/references/quiz-funnel-copy.md create mode 100644 copywriting/references/real-world-examples-finance-investing-apps.md create mode 100644 copywriting/references/references.md create mode 100644 copywriting/references/skill-integration.md create mode 100644 copywriting/references/test-app-store-screenshot-order.md create mode 100644 copywriting/references/the-seven-sweeps-copy-editing-framework.md create mode 100644 copywriting/references/writing_styles.md create mode 100644 growth/references/cro-frameworks.md create mode 100644 launch-strategy/SKILL.md create mode 100644 marketing-psychology/SKILL.md create mode 100644 paid-ads/SKILL.md create mode 100644 pricing-strategy/SKILL.md create mode 100644 product-marketing-context/SKILL.md create mode 100644 referral-program/SKILL.md create mode 100644 seo-research/references/site-architecture.md diff --git a/README.md b/README.md index 3948417..35e1acf 100644 --- a/README.md +++ b/README.md @@ -13,22 +13,25 @@ This repo is my personal skills directory. Skills are prompt templates that Open --- -## My Original Skills +```bash +cp -r ~/Projects/erics-skills/skills/copywriting ~/.clawdbot/skills/ +``` + +## Skills ### Content & Writing | Skill | Description | |-------|-------------| -| [article-writer](article-writer/) | Write article drafts from approved outlines with SEO and brand voice | -| [brand-identity](brand-identity/) | Build a complete brand identity: purpose, values, voice, visual system, guidelines | -| [content-pipeline](content-pipeline/) | Orchestrator for the 3-article content pipeline with parallel sub-agents | -| [content-strategy](content-strategy/) | Build content strategy: hooks, angles, and ideas from what's trending now | -| [editor-in-chief](editor-in-chief/) | Autonomous editing orchestrator: diagnose, fix, and iterate drafts to quality | -| [evaluate-content](evaluate-content/) | Judge content quality: shareability, readability, voice, cuttability, angle | -| [hooks](hooks/) | Generate headlines, titles, and scroll-stopping openers | -| [outline-generator](outline-generator/) | Generate structured article outlines from approved hooks | -| [substack-draft](substack-draft/) | Save finished articles to Substack as drafts | -| [tweet-ideas](tweet-ideas/) | Generate standalone tweet ideas (Aaron Levie playbook) | +| [copywriting](copywriting/SKILL.md) | write ad copy: App Store listings, Google Ads, landing pages, TikTok/Meta scripts, push, email. | +| [article-writer](article-writer/SKILL.md) | write article drafts from approved outlines with SEO and brand voice. | +| [content-atomizer](content-atomizer/SKILL.md) | repurpose long-form content into platform-native pieces for 8+ channels. | +| [editor-in-chief](editor-in-chief/SKILL.md) | autonomous editing orchestrator: diagnose, fix, and iterate drafts to quality. | +| [evaluate-content](evaluate-content/SKILL.md) | judge content quality: shareability, readability, voice, cuttability, angle. | +| [headlines](headlines/SKILL.md) | generate headlines, titles, and hooks for content. | +| [outline-generator](outline-generator/SKILL.md) | generate structured article outlines from approved headlines. | +| [substack-draft](substack-draft/SKILL.md) | save finished articles to Substack as drafts. | +| [tweet-ideas](tweet-ideas/SKILL.md) | generate standalone tweet ideas about a topic (Aaron Levie playbook). | ### Marketing & Growth @@ -124,93 +127,19 @@ This repo is my personal skills directory. Skills are prompt templates that Open | Skill | Description | |-------|-------------| -| [alpaca](alpaca/) | Trade stocks and crypto via Alpaca API | -| [another-perspective](another-perspective/) | Multi-perspective council analysis on decisions | -| [cloud-migration](cloud-migration/) | Full cloud provider migrations end-to-end | -| [porkbun](porkbun/) | Manage domains, DNS, SSL via Porkbun API | -| [railway](railway/) | Deploy and manage Railway projects via CLI and MCP | -| [sahil-office-hours](sahil-office-hours/) | Startup advice frameworks from Sahil Lavingia (Gumroad) | -| [yc-office-hours](yc-office-hours/) | YC office hours prep | - -### OpenClaw & Infrastructure - -| Skill | Description | -|-------|-------------| -| [openclaw-memory-setup](openclaw-memory-setup/) | Set up a complete memory system for an OpenClaw instance | -| [openclaw-resiliency](openclaw-resiliency/) | Gateway watchdog for health monitoring and auto-recovery | -| [security-audit](security-audit/) | Security audit for codebases and deployments | - -### Automated Pipelines (Cron) - -| Skill | Description | -|-------|-------------| -| [earnings-card-pipeline](earnings-card-pipeline/) | Weekly earnings event cards for social (Mon 8 AM ET) | -| [post-bloom-features](post-bloom-features/) | Screenshot new features, render social cards (Tue/Thu 1 AM ET) | -| [post-insider-trades](post-insider-trades/) | Scrape insider buys, generate trade cards (weekdays 9 AM + 2 PM ET) | -| [post-investinglog-trades](post-investinglog-trades/) | Post trade cards from investing-log (weekdays 4 PM ET) | - -### UI/UX - -| Skill | Description | -|-------|-------------| -| [userinterface-wiki](userinterface-wiki/) | UI/UX best practices: animations, CSS, typography, UX patterns | - -### Other - -| Skill | Description | -|-------|-------------| -| [document-release](document-release/) | Document release processes | - ---- - -## Adapted Skills - -These started from other open-source projects. I've modified and extended them for my workflows. Links to the originals: - -### From [Anthropic](https://github.com/anthropics) - -| Skill | Original | -|-------|----------| -| [documents](documents/) | [anthropics/skills](https://github.com/anthropics/skills) | -| [wealth-management](wealth-management/) | [anthropics/financial-services-plugins](https://github.com/anthropics/financial-services-plugins) | -| [skill-creator](skill-creator/) | [anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev) | -| [skill-improver](skill-improver/) | [anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev) | -| [visual-design/frontend-design](visual-design/frontend-design/) | [anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) | -| [ralph-mode](ralph-mode/) | [anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) | - -### From [obra/superpowers](https://github.com/obra/superpowers) - -| Skill | Description | -|-------|-------------| -| [superpowers-coding](superpowers-coding/) | TDD-first feature implementation and systematic debugging | -| [superpowers-planning](superpowers-planning/) | Explore intent and create detailed plans before touching code | -| [superpowers-reviews](superpowers-reviews/) | Code review, branch finishing, batch execution with checkpoints | - -### From [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) - -| Skill | Description | -|-------|-------------| -| [growth](growth/) | Full-funnel growth: CRO, onboarding, paywalls, churn, launches, pricing | -| [churn-prevention](churn-prevention/) | Subscription retention, cancel flows, save offers, dunning | -| [email-sequence](email-sequence/) | Email sequences, drip campaigns, lifecycle messaging | -| [ad-copy](ad-copy/) | Direct response copy for any platform | -| [positioning-angles](positioning-angles/) | Product positioning, strategic angles, value propositions | - -### From Other Projects - -| Skill | Original | -|-------|----------| -| [codex](codex/) | [garrytan/gstack](https://github.com/garrytan/gstack) (MIT) | -| [impeccable](impeccable/) | [pbakaus/impeccable](https://github.com/pbakaus/impeccable) | -| [app-store-screenshots](app-store-screenshots/) | [ParthJadhav/app-store-screenshots](https://github.com/ParthJadhav/app-store-screenshots) | -| [video-production/remotion-videos](video-production/remotion-videos/) | [remotion-dev/skills](https://github.com/remotion-dev/skills) | -| [visual-design/frontend-slides](visual-design/frontend-slides/) | [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides) | -| [last30days](last30days/) | [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) | -| [stably-cli](stably-cli/) | [skills.sh/stablyai](https://skills.sh/stablyai/agent-skills/stably-cli) | -| [stably-sdk-rules](stably-sdk-rules/) | [skills.sh/stablyai](https://skills.sh/stablyai/agent-skills/stably-sdk-rules) | -| [sahil-office-hours](sahil-office-hours/) | [slavingia/skills](https://github.com/slavingia/skills) | - ---- +| [copywriting](copywriting/SKILL.md) | Page copy frameworks + direct response for any platform (ads, App Store, landing pages, scripts). | +| [marketing-psychology](marketing-psychology/SKILL.md) | Psychological principles, mental models, and behavioral science for marketing. | +| [pricing-strategy](pricing-strategy/SKILL.md) | Pricing decisions, tier packaging, value metrics, monetization strategy. | +| [launch-strategy](launch-strategy/SKILL.md) | Product launches, feature announcements, Product Hunt, go-to-market. | +| [paid-ads](paid-ads/SKILL.md) | Paid advertising strategy: platform selection, targeting, creative, optimization. | +| [referral-program](referral-program/SKILL.md) | Referral and affiliate program design, optimization, and measurement. | +| [cold-email](cold-email/SKILL.md) | B2B cold email writing and follow-up sequences. | +| [product-marketing-context](product-marketing-context/SKILL.md) | Create product marketing context doc referenced by all marketing skills. | +| [create-a-sales-asset](visual-design/create-a-sales-asset/SKILL.md) | generate sales assets (landing pages, decks, one-pagers). | +| [dogfood](dogfood/SKILL.md) | QA and exploratory test web applications, produce structured reports. | +| [growth](growth/SKILL.md) | full-funnel growth: CRO, onboarding, paywalls, churn, launches, pricing. | +| [positioning-angles](positioning-angles/SKILL.md) | define product positioning angles and strategic frames. | +| [wealth-management](wealth-management/SKILL.md) | client reviews, financial plans, investment proposals, portfolio rebalancing, tax-loss harvesting. | ## Installation diff --git a/ad-copy/SKILL.md b/ad-copy/SKILL.md deleted file mode 100644 index cc92eab..0000000 --- a/ad-copy/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: ad-copy -description: "Write direct response copy for any platform — App Store, Google Ads, landing pages, TikTok, Meta, push, email." ---- -# Direct Response Copy - -Copy that converts. Not content that entertains. - -**The distinction matters.** Content marketing builds audience over time (blog posts, newsletters, thought leadership). Direct response gets someone to take a specific action RIGHT NOW (download the app, start a free trial, subscribe, buy). Every word either moves toward the conversion or it's dead weight. Cut it. - -## Core Copy Formula - -**Emotional Promise + Rational Explanation.** - -1. Open with what the customer *achieves* (not what the product does). Ship faster. Invest smarter. Feel calm. -2. Follow immediately with the rational "how" — what the product actually does to deliver that promise. - -> "Hedge funds run AI-powered research 24/7. Bloom gives retail investors the same thing for $12/month." — Promise (parity with institutions), then rational delivery (AI research, specific price). - -Mix with: stories (yours or customers'), testimonials, specific numbers. That's the full recipe for copy people actually read. - -**What to cut:** -- Superlatives ("the best," "the fastest," "the most popular") — claim the outcome instead -- "Streamline" and "supercharge" — say what actually happens -- Feature bullet lists over 5 items — people won't remember them; pick your strongest 3 -- Writing about yourself — every "we" that can be a "you" should be a "you" - -## References - -This skill content is modularized into reference docs for readability. - -- [Brand Voice Reference](references/brand-voice-reference.md) -- [Skill Integration](references/skill-integration.md) -- [Direct Response Principles](references/direct-response-principles.md) -- [Platform Character Limits Reference](references/platform-character-limits-reference.md) -- [1. App Store Descriptions](references/1-app-store-descriptions.md) -- [2. Google Ads](references/2-google-ads.md) -- [3. Landing Pages](references/3-landing-pages.md) -- [4. TikTok / Meta Ad Scripts](references/4-tiktok-meta-ad-scripts.md) -- [5. Push Notifications](references/5-push-notifications.md) -- [6. Email Sequences](references/6-email-sequences.md) -- [7. UGC Script Templates](references/7-ugc-script-templates.md) -- [Quiz Funnel Copy](references/quiz-funnel-copy.md) -- [A/B Testing Framework](references/a-b-testing-framework.md) -- [Test: App Store Screenshot Order](references/test-app-store-screenshot-order.md) -- [Copy Anti-Patterns (Kill on Sight)](references/copy-anti-patterns-kill-on-sight.md) -- [Real-World Examples (Finance/Investing Apps)](references/real-world-examples-finance-investing-apps.md) -- [The Seven Sweeps (Copy Editing Framework)](references/the-seven-sweeps-copy-editing-framework.md) -- [Process: Writing Copy with This Skill](references/process-writing-copy-with-this-skill.md) -- [Quick Reference: CTA Library](references/quick-reference-cta-library.md) -- [References](references/references.md) diff --git a/churn-prevention/SKILL.md b/churn-prevention/SKILL.md index 0cf0b44..ebaeaaa 100644 --- a/churn-prevention/SKILL.md +++ b/churn-prevention/SKILL.md @@ -11,7 +11,7 @@ You are an expert in subscription retention and churn prevention. Your goal is t ## Before Starting -Read `product-marketing-context.md` in the workspace root if it exists. +Read `.agents/product-marketing-context.md` if it exists. Gather this context (ask if not provided): @@ -422,6 +422,7 @@ Test one variable at a time: | **Churnkey** | Full cancel flow + dunning | AI-powered adaptive offers, ~34% avg save rate | | **ProsperStack** | Cancel flows with analytics | Advanced rules engine | | **Raaft** | Simple cancel flow builder | Easy setup, good for early-stage | +| **Chargebee Retention** | Chargebee customers | Native integration, was Brightback | ### Billing Providers (Dunning) diff --git a/cold-email/SKILL.md b/cold-email/SKILL.md new file mode 100644 index 0000000..e2c26a3 --- /dev/null +++ b/cold-email/SKILL.md @@ -0,0 +1,121 @@ +--- +name: cold-email +description: "Write B2B cold emails and follow-up sequences that get replies. Use when someone wants cold outreach, prospecting emails, SDR emails, or says 'nobody's replying to my emails.'" +metadata: + version: 1.0.0 +--- + +# Cold Email Writing + +Expert cold email writer. Write emails that sound like they came from a sharp, thoughtful human, not a sales machine. + +## Before Writing + +Read `.agents/product-marketing-context.md` if it exists — it contains product name, audience, and positioning context. + +Understand the situation (ask if not provided): + +1. **Who are you writing to?** Role, company, why them specifically +2. **What do you want?** The outcome (meeting, reply, intro, demo) +3. **What's the value?** The specific problem you solve for people like them +4. **What's your proof?** A result, case study, or credibility signal +5. **Any research signals?** Funding, hiring, LinkedIn posts, company news, tech stack changes + +Work with whatever the user gives you. Don't block on missing inputs. + +--- + +## Writing Principles + +### Write like a peer, not a vendor +The email should read like it came from someone who understands their world. Use contractions. Read it aloud. + +### Every sentence must earn its place +Cold email is ruthlessly short. If a sentence doesn't move toward replying, cut it. + +### Personalization must connect to the problem +If you remove the personalized opening and the email still makes sense, the personalization isn't working. + +### Lead with their world, not yours +"You/your" should dominate over "I/we." Don't open with who you are. + +### One ask, low friction +Interest-based CTAs ("Worth exploring?") beat meeting requests. One CTA per email. + +--- + +## Voice & Tone + +**Target voice:** A smart colleague who noticed something relevant and is sharing it. + +**Calibrate to audience:** +- C-suite: ultra-brief, peer-level, understated +- Mid-level: more specific value, slightly more detail +- Technical: precise, no fluff, respect their intelligence + +**What it should NOT sound like:** +- A template with fields swapped in +- A pitch deck in paragraph form +- An AI-generated email ("I hope this email finds you well," "leverage," "synergy") + +--- + +## Structure + +Common shapes that work: + +- **Observation → Problem → Proof → Ask**: You noticed X, which usually means Y. We helped Z. Interested? +- **Question → Value → Ask**: Struggling with X? We do Y. Company Z saw [result]. Worth a look? +- **Trigger → Insight → Ask**: Congrats on X. That usually creates Y challenge. Curious? +- **Story → Bridge → Ask**: [Similar company] had [problem]. They [solved it this way]. Relevant? + +--- + +## Subject Lines + +Short, boring, internal-looking. The subject line's only job is to get opened. + +- 2-4 words, lowercase, no punctuation tricks +- Should look like it came from a colleague ("reply rates," "hiring ops," "Q2 forecast") +- No product pitches, no urgency, no emojis, no prospect's first name + +--- + +## Follow-Up Sequences + +Each follow-up should add something new: a different angle, fresh proof, a useful resource. "Just checking in" gives no reason to respond. + +- 3-5 total emails, increasing gaps between them +- Each email should stand alone +- The breakup email is your last touch: honor it + +--- + +## Quality Check + +Before sending: +- Does it sound like a human wrote it? (Read it aloud) +- Would YOU reply to this? +- Does every sentence serve the reader, not the sender? +- Is the personalization connected to the problem? +- Is there one clear, low-friction ask? + +--- + +## What to Avoid + +- "I hope this email finds you well" or "My name is X and I work at Y" +- Jargon: "synergy," "leverage," "circle back," "best-in-class" +- Feature dumps: one proof point beats ten features +- HTML, images, or multiple links +- Fake "Re:" or "Fwd:" subject lines +- Asking for 30-minute calls in first touch +- "Just checking in" follow-ups + +--- + +## Related Skills + +- **copywriting**: For landing pages and web copy +- **email-sequence**: For lifecycle/nurture email sequences (not cold outreach) +- **content-strategy**: For content that warms up prospects diff --git a/content-strategy/SKILL.md b/content-strategy/SKILL.md index 96ff789..532bbb5 100644 --- a/content-strategy/SKILL.md +++ b/content-strategy/SKILL.md @@ -86,7 +86,7 @@ Write all three, then pick the right one for the format: - **Visual** — what they SEE in the first frame - **Audio** — what they HEAR in the first 3 seconds -> **Load on-demand:** `hooks` skill has 15+ proven hook formulas. +> **Load on-demand:** `headlines` skill has 15+ proven hook formulas. ### Hook Psychology Triggers @@ -156,7 +156,25 @@ Match the angle to a format that amplifies it. | Tier List | Gamified ranking format; viewers argue placements in comments, driving engagement | Content strategy, tool reviews, platform comparisons, "best of" lists | | Viral Breakdown / Reaction | Dual-screen commentary on a viral post; borrowed traffic + authority positioning | Creator education, niche analysis, weekly pillar content | -> **See:** `references/content-formats.md` for the "Hands-Doing-Something" format details, structure, and Bloom application. +### The "Hands-Doing-Something" Format + +A viral format where the creator does a simple tactile task (cutting fruit, making tea, crafting) while speaking about a completely unrelated topic. The visual activity is background; the spoken content is the payload. + +Source: @thebranding.ai breakdown of multiple creators going viral with the same format. + +**Why it works:** +- Tactile hand activity holds visual attention subconsciously (the eye tracks movement) +- The mismatch between casual activity and spoken content creates curiosity ("why is she cutting an apple while talking about studying?") +- Extremely simple production: phone on a stand, good mic, something to do with your hands +- Scalable to any niche: investing (writing in a notebook), cooking (prep work), fitness (stretching), tech (unboxing) + +**Structure:** +1. Open with a relatable spoken hook ("you don't wanna study? that's fine, just imagine...") +2. Hands doing something throughout (never stop the activity) +3. Deliver value through speech while the visual activity anchors attention +4. Close with soft CTA or open loop + +**Bloom application:** Film hands writing stock tickers on a notepad, scrolling through the Bloom app, or organizing investment notes while delivering investing insights via voiceover. | Audience Temp | Best Formats | |--------------|-------------| @@ -228,7 +246,38 @@ One file per episode: `~/clawd/characters//scripts/YYYY-MM-DD-episode-titl --- -> **See:** `references/content-formats.md` for viral breakdown pillar details, dual-screen format, on-screen labels, and Bloom-specific examples. +## Step 2d: Viral Breakdown Pillar + +This is a full account pillar — not a one-off format. Run it every week. + +**How it works:** +- Pick 1–3 viral posts in your niche each week +- React to + annotate them in dual-screen format (your face/commentary + the source post side by side) +- Explain the *specific mechanics* of why it worked — not "it's good," but "the credibility drop at 0:08 + the stacked loop at 0:14 are why retention holds past 30 seconds" +- Label every piece "pt 1" even if there's no pt 2 yet — it signals series, invites return visits, and the algorithm treats it as episodic + +**Why it compounds:** +| Benefit | Mechanism | +|---------|-----------| +| Borrowed traffic | Your content surfaces in searches and feeds for the source post's audience | +| Authority positioning | You're the person who understands the craft, not just a consumer | +| Series architecture | Built-in return reason; viewers expect more installments | + +**Format:** Dual-screen reaction (split-screen or side-by-side layout). If screen recording isn't possible, show the source clip and annotate with on-screen text labels while reacting verbally. + +**On-screen keyword labels (retention device):** As you narrate your breakdown, flash bold single-word or short-phrase labels on screen that name the tactic being used: "HOOK", "AVATAR", "MESSAGING", "OPEN LOOP", "SOCIAL PROOF", etc. This serves three purposes: +1. Viewers feel like they're learning a *system*, not just watching a reaction +2. Labels create visual rhythm that sustains attention through the middle of the video (the retention dead zone) +3. Each label is a micro-open-loop: the viewer wants to understand *why* you labeled it that, so they keep watching + +Place labels at the moment you identify the tactic, not before. Let the source video play 2-3 seconds first, then drop the label as your "aha" moment. Use bold white or colored text, large enough to read on mobile, centered or near the source video panel. + +**Bloom-specific example:** +- Source: viral TikTok of someone showing their Robinhood portfolio down 40% (2M+ views) +- Labels you'd drop: "LOSS AVERSION" (the emotional hook), "ROUND NUMBER" (they lost exactly $10K, not $9,847), "SCREENSHOT FORMAT" (looks organic, not produced), "NO CTA" (the virality IS the content, no ask) +- Your commentary: explain each label as an investing psychology + content strategy concept simultaneously. Double value for the viewer. + +**Sourcing:** Use `last30days`, `grok-search`, or `trend-research` to find viral posts in the investing/personal finance niche weekly. Look for 50K+ views, especially from accounts under 10K followers (pre-algo signal). --- @@ -241,9 +290,9 @@ Don't write here. Route to the right skill. | Tweets / X posts | `tweet-ideas` | | Articles / long-form | `article-writer` | | TikTok slideshows | `slideshow-creator` | -| Hooks and headlines | `hooks` | -| Ad copy (paid) | `ad-copy` | -| Paid creative concepts | `ad-copy` (includes A/B blitz protocol) | +| Hooks and headlines | `headlines` | +| Ad copy (paid) | `copywriting` | +| Paid creative concepts | `copywriting` (includes A/B blitz protocol) | | AI character video scripts | Write inline using Step 2c above | | New AI character | `character-creation` | @@ -256,11 +305,42 @@ Don't write here. Route to the right skill. | LinkedIn, X, Threads | `typefully` skill | | TikTok | `slideshow-creator` / ReelFarm | -> **See:** `references/distribution.md` for queue minimums and batch scheduling cadence. +**Queue minimums:** + +| Platform | Min Queue | Cadence | +|---------|-----------|---------| +| LinkedIn | 7 posts | 1/day | +| X | 14 posts | 2/day | +| TikTok | 14-21 posts | 2-3/day | +| Threads | 7 posts | 1/day | + +Batch at least 7 days per session. Never schedule one post at a time. If queue drops below 3 days, refill immediately. > **Load on-demand:** `references/calendar-batching.md` for scheduling strategy and optimal posting times. -> **See:** `references/geo-targeting.md` for Instagram/Reels geo-targeting strategy, location tags, localization rules, and the 4-phase regional batch framework. +### Geo-Targeting (Instagram / Reels) + +Most brands compete in the same saturated metros. Regional markets have lower CPMs, less competition, and engaged audiences who see far less branded content. + +**Layer 1 — Native location tags (fully compliant):** +- Use Instagram's existing location tag library; attach regional business district tags (not just city name) when posting +- Target specific coworking hubs, financial districts, tech clusters — not "New York City" +- Surfaces content in location-specific story feeds and Explore pages at zero additional media spend + +**Layer 2 — Custom location tags (gray area):** +- Create new tags via Facebook check-in + VPN to target underserved areas with no existing tag +- Carries account-level risk if pattern is detectable; vary IP patterns, ensure content is genuinely relevant + +**Localization rules (content must feel native, not just tagged):** +- Adapt industry context reference in the hook to match dominant industry in target city +- Adapt business size + operational framing to local business profile +- Adjust tone register: warmer/relationship-oriented in southern markets, direct/efficiency-focused in northern/western + +**4-Phase Regional Batch Framework:** +1. **Market selection** — use Instagram Insights for existing follower geography + check location tag feed competition. Pick 8–12 test markets. +2. **Production** — write base script, adapt 2–3 localization elements per variant (hook industry ref, operational framing, pain point language). Tag to specific business districts. Schedule at local peak hours (6:30–8:30am, 12–1:30pm, 6:30–9pm local time). +3. **Evaluate (weeks 2–4)** — rank markets by organic discovery rate + engagement quality. Top 3–5 markets get paid amplification. +4. **Deepen** — produce second-generation content for winning markets with deeper localization; expand test cohort using learnings. --- @@ -350,27 +430,107 @@ What a complete strategy card looks like after running this skill. Use this as t **Awareness level targeted:** Level 1–2 cold, Level 3–4 retargeted **Delegate to:** -- Visuals → `ad-copy` + `nano-banana-pro` +- Visuals → `copywriting` + `nano-banana-pro` - Tweets → `tweet-ideas` - TikTok → `slideshow-creator` - Scheduling → `typefully` --- -> **See:** `references/content-formats.md` for creator activity tier list (S through F ranking by impact). +## Creator Activity Tier List + +What to spend your time on as a content creator, ranked by impact. Based on @wootak's framework (https://www.instagram.com/reel/DVwed_xEvHx/). + +| Tier | Activity | Why | +|------|----------|-----| +| **S** | **Post consistently** | Nothing else matters if you don't publish. Ship beats perfect. | +| **S** | **Define your niche/target** | Focused content reaches the right people. Broad content reaches nobody. | +| **S** | **Use TikTok (especially TikTok Shop)** | Highest-leverage platform for organic discovery right now. | +| **S** | **Repurpose content cross-platform** | Every platform's audience sees it "for the first time." One piece of content = 3-5 posts. | +| **A** | **Script/outline before filming** | Structure beats improv. But execution (posting) matters more than perfect scripts. | +| **A** | **Track analytics** | Know what works. But analysis without posting is procrastination. | +| **A** | **Post at optimal times** | Helps, but doesn't replace quality or consistency. | +| **B** | **Writing elaborate captions** | Useful but overrated. Most creators over-invest here relative to impact. | +| **C** | **Written/text-only content** | Video outperforms text on every social platform. Text content is C tier in a video-first world. | +| **F** | **Hashtags** | Zero meaningful impact on modern algorithms. Complete waste of effort. | + +The hierarchy: **Posting > Targeting > Platform choice > Repurposing > Scripting > Analytics > Timing > Captions > Text content > Hashtags.** + +--- + +## Channel Tier List (Bloom / B2C) + +What actually works for consumer apps vs. what sounds good but doesn't. + +**High-signal channels:** +- TikTok / Instagram Reels — primary B2C organic discovery; recreate before recruiting creators +- Influencer/creator marketing — TikTok/YouTube/Instagram. Lovable ($400M ARR) spends 10x more on influencer marketing than paid social and considers it their key growth driver. Validate formats with your own account first, then hand proven formats to creators. This should be the primary paid channel, not Meta ads. +- Free credits / freemium as marketing — treat free tier as a marketing channel, not a cost center. "Our free giveaways are bigger than paid marketing spend." (Lovable CEO, 20VC March 2026) +- Free SEO tools — high-value lead magnets, easier to rank than blog posts, builds backlinks +- Email marketing — works if sequences are built correctly (see growth skill); people do read emails + +**Questionable-signal channels (test carefully):** +- Meta/Facebook ads — Lovable's CEO at $400M ARR: "Meta ads have little incrementality; pass through views which don't materialize into anything. I haven't seen them work in a while." (Lenny's Podcast, Dec 2025). If running Meta ads, watch incrementality closely: are installs you're paying for ones that would have happened organically? Compare install lift when ads are paused vs. running. + +**Low-signal channels (avoid or deprioritize):** +- Newsletter sponsorships — expensive and most clicks are bots +- Twitter ads — worst targeting in the industry; not worth the spend +- Google ads — more expensive than Facebook for consumer apps, higher irrelevant clicks +- Referral programs — very hard to make work; only viable with stable conversion and large customer base +- Reddit audience building — ban risk is high; answering long-tail questions can work, but building an audience there doesn't +- Beta directories (BetaList, etc.) — mostly dead; not worth the setup + +**Alternative funnel: Quiz-based landing pages** + +Instead of Ad → App Store → Install, run Ad → Web Quiz → Personalized Results → App Store. A quiz between the ad and the offer warms cold traffic through micro-commitments. DTC benchmark: cold traffic conversion jumped from 1.2% to 4.7% with a quiz funnel (@DTC_Quizbuilder, $2M in 90 days). + +Why it works for apps: +- Each question answered is a small "yes" that compounds (sunk cost) +- Questions seed beliefs and pre-handle objections before the user sees pricing +- Non-completers give you zero-party data for segmented retargeting (someone who answered "I struggle with timing the market" gets a different retargeting ad than someone who answered "I don't know what to invest in") +- The loading/results screen is captive attention: 10-15s where you show testimonials, social proof, and app previews while "calculating their results" + +Quiz sequencing that converts: +1. Q1-Q2: Low-friction demographics (age, experience level). Zero cognitive load, starts the yes-chain. +2. Q3-Q4: Aspirational goals ("What's your investing goal?"). Emotional questions hit harder after they've committed. +3. Q5-Q6: Pain points and struggles. Now they've told you their problems. +4. Breather slide with social proof after Q4. +5. Results page → personalized app recommendation → App Store link. + +Drop-off benchmarks: Q1 = 30-40% drop-off (normal, biggest filter). Remaining questions: under 15% each. Overall completion: aim for 25%+. If any single question has 10%+ drop-off, simplify it (fewer options, add "None of the above"). + +Retargeting play: Everyone who takes the quiz but doesn't install gave you data. Segment retargeting by their answers: "tried other investing apps" → ad about why Bloom's AI is different. "Low confidence in stock picks" → ad about AI-powered research. Specific beats generic. + +Bloom application: The onboarding flow already asks risk tolerance and goals post-install. A pre-install web quiz version of this would warm traffic before the App Store page, and the data feeds retargeting even if they never install. + +Source: @DTC_Quizbuilder thread (https://x.com/DTC_Quizbuilder/status/2010379560769015885) + +**SEO timing:** +- Don't prioritize SEO before your first customers — takes months to kick in, and if you pivot the product, the work goes to zero +- When you do SEO: free tools first (easier to rank, more shareable, generate backlinks naturally), then long-tail blog posts with purchase intent, then programmatic data-driven pages --- -> **See:** `references/distribution.md` for channel tier list (high-signal, questionable-signal, low-signal channels) and SEO timing. +## Reference Files -> **See:** `references/interactive-content.md` for quiz-based landing page funnels, sequencing, drop-off benchmarks, and retargeting play. +| File | Contents | +|------|----------| +| `references/social-content.md` | Social media strategy: content pillars, hook formulas, calendars, engagement, repurposing, analytics | +| `references/free-tool-strategy.md` | Engineering-as-marketing: tool types, ideation, evaluation scorecard, lead capture | +| `references/lead-magnets.md` | Lead magnet types, buyer stage matching, gating strategy, distribution, benchmarks | +| `references/marketing-ideas.md` | 139 SaaS marketing ideas catalog organized by category, stage, and budget | +| `references/blog-seo-planning.md` | Searchable vs shareable, content pillars, topic clusters, buyer stage keywords, ideation sources | +| `references/6-elements-framework.md` | Content creation framework | +| `references/copywriting-formulas.md` | Copywriting formulas for social content | +| `references/creative-research-methods.md` | How to research what's working | +| `references/ad-formats-library.md` | Ad format reference library | --- ## Related Skills -- `hooks` — hook formulas and title generation -- `ad-copy` — direct response copy, brand voice, A/B testing blitz +- `headlines` — hook formulas and title generation +- `copywriting` — page copy, direct response, brand voice, A/B testing blitz - `tweet-ideas` — standalone tweet content - `article-writer` — long-form drafts - `slideshow-creator` — TikTok production and ReelFarm automation diff --git a/content-strategy/references/blog-seo-planning.md b/content-strategy/references/blog-seo-planning.md new file mode 100644 index 0000000..13d3d07 --- /dev/null +++ b/content-strategy/references/blog-seo-planning.md @@ -0,0 +1,153 @@ +# Blog & SEO Content Planning + +Frameworks for deciding what content to create, organizing topics into clusters, and matching content to the buyer journey. + +--- + +## Searchable vs Shareable + +Every piece of content must be searchable, shareable, or both. Prioritize search: it captures existing demand. + +**Searchable content** captures existing demand. Optimized for people actively looking for answers. + +**Shareable content** creates demand. Spreads ideas and gets people talking. + +### When Writing Searchable Content +- Target a specific keyword or question +- Match search intent exactly +- Use clear titles that match search queries +- Structure with headings that mirror search patterns +- Provide comprehensive coverage +- Include data, examples, and authoritative sources +- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency + +### When Writing Shareable Content +- Lead with a novel insight, original data, or counterintuitive take +- Challenge conventional wisdom with well-reasoned arguments +- Tell stories that make people feel something +- Create content people want to share to look smart or help others +- Connect to current trends or emerging problems + +--- + +## Searchable Content Types + +### Use-Case Content +Formula: [persona] + [use-case]. Targets long-tail keywords. +- "Project management for designers" +- "Task tracking for developers" + +### Hub and Spoke +Hub = comprehensive overview. Spokes = related subtopics. +``` +/topic (hub) +├── /topic/subtopic-1 (spoke) +├── /topic/subtopic-2 (spoke) +└── /topic/subtopic-3 (spoke) +``` +Create hub first, then build spokes. Interlink strategically. + +**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth. + +### Template Libraries +High-intent keywords + product adoption. Target searches like "marketing plan template." Provide standalone value, show how product enhances the template. + +--- + +## Shareable Content Types + +### Thought Leadership +- Articulate concepts everyone feels but hasn't named +- Challenge conventional wisdom with evidence +- Share vulnerable, honest experiences + +### Data-Driven Content +- Product data analysis (anonymized insights) +- Public data analysis (uncover patterns) +- Original research (run experiments, share results) + +### Expert Roundups +15-30 experts answering one specific question. Built-in distribution. + +### Case Studies +Structure: Challenge → Solution → Results → Key learnings. + +### Meta Content +Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC." + +--- + +## Content Pillars and Topic Clusters + +Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content. + +### How to Identify Pillars +1. **Product-led**: What problems does your product solve? +2. **Audience-led**: What does your ICP need to learn? +3. **Search-led**: What topics have volume in your space? +4. **Competitor-led**: What are competitors ranking for? + +### Pillar Structure +``` +Pillar Topic (Hub) +├── Subtopic Cluster 1 +│ ├── Article A +│ ├── Article B +│ └── Article C +├── Subtopic Cluster 2 +│ ├── Article D +│ └── Article E +└── Subtopic Cluster 3 + ├── Article F + └── Article G +``` + +### Pillar Criteria +Good pillars should: align with your product/service, match audience interests, have search volume and/or social interest, be broad enough for many subtopics. + +--- + +## Keyword Research by Buyer Stage + +### Awareness Stage +Modifiers: "what is," "how to," "guide to," "introduction to" + +### Consideration Stage +Modifiers: "best," "top," "vs," "alternatives," "comparison" + +### Decision Stage +Modifiers: "pricing," "reviews," "demo," "trial," "buy" + +### Implementation Stage +Modifiers: "templates," "examples," "tutorial," "how to use," "setup" + +--- + +## Content Ideation Sources + +1. **Keyword data**: Topic clusters, buyer stage mapping, quick wins (low competition + decent volume) +2. **Call transcripts**: Questions, pain points, objections, customer language +3. **Survey responses**: Open-ended themes, resource requests, format preferences +4. **Forum research**: Reddit (`site:reddit.com [topic]`), Quora, Indie Hackers, HN +5. **Competitor analysis**: `site:competitor.com/blog`, gaps, outdated content to improve +6. **Sales and support**: Common objections, repeated questions, support ticket patterns + +--- + +## Prioritizing Content Ideas + +Score on four factors: + +| Factor | Weight | +|--------|--------| +| Customer Impact | 40% | +| Content-Market Fit | 30% | +| Search Potential | 20% | +| Resource Requirements | 10% | + +### Scoring Template + +| Idea | Impact (40%) | Fit (30%) | Search (20%) | Resources (10%) | Total | +|------|-------------|-----------|--------------|-----------------|-------| +| Topic A | 8 | 9 | 7 | 6 | 8.0 | +| Topic B | 6 | 7 | 9 | 8 | 7.1 | diff --git a/content-strategy/references/free-tool-strategy.md b/content-strategy/references/free-tool-strategy.md new file mode 100644 index 0000000..cb63657 --- /dev/null +++ b/content-strategy/references/free-tool-strategy.md @@ -0,0 +1,113 @@ +# Free Tool Strategy (Engineering as Marketing) + +Plan and evaluate free tools that generate leads, attract organic traffic, and build brand awareness. + +--- + +## Core Principles + +1. **Solve a real problem**: Tool must provide genuine value, useful even without your main product. +2. **Adjacent to core product**: Related to what you sell, natural path from tool to product. +3. **Simple and focused**: Does one thing well, low friction to use, immediate value. +4. **Worth the investment**: Lead value x expected leads > build cost + maintenance. + +--- + +## Tool Types + +| Type | Examples | Best For | +|------|----------|----------| +| Calculators | ROI, savings, pricing estimators | Decisions involving numbers | +| Generators | Templates, policies, names | Creating something quickly | +| Analyzers | Website graders, SEO auditors | Evaluating existing work | +| Testers | Meta tag preview, speed tests | Checking if something works | +| Libraries | Icon sets, templates, snippets | Reference material | +| Interactive | Tutorials, playgrounds, quizzes | Learning/understanding | + +--- + +## Ideation Framework + +### Start with Pain Points + +1. **What problems does your audience Google?** Search query research, common questions. +2. **What manual processes are tedious?** Spreadsheet tasks, repetitive calculations. +3. **What do they need before buying your product?** Assessments, planning, comparisons. +4. **What information do they wish they had?** Data they can't easily access, benchmarks. + +### Validate the Idea +- **Search demand**: Is there search volume? How competitive? +- **Uniqueness**: What exists? How can you be 10x better? +- **Lead quality**: Does this audience match buyers? +- **Build feasibility**: How complex? Can you scope an MVP? + +--- + +## Lead Capture Strategy + +### Gating Options + +| Approach | Pros | Cons | +|----------|------|------| +| Fully gated | Maximum capture | Lower usage | +| Partially gated | Balance of both | Common pattern | +| Ungated + optional | Maximum reach | Lower capture | +| Ungated entirely | Pure SEO/brand | No direct leads | + +### Best Practices +- Value exchange clear: "Get your full report" +- Minimal friction: Email only +- Show preview of what they'll get +- Optional: Segment by asking one qualifying question + +--- + +## SEO Considerations + +### Keyword Strategy +**Tool landing page**: "[thing] calculator", "[thing] generator", "free [tool type]" +**Supporting content**: "How to [use case]", "What is [concept]" + +### Link Building +Free tools attract links because they're genuinely useful, unique, and shareable. + +--- + +## Build vs. Buy + +| Approach | When | +|----------|------| +| Build custom | Unique concept, core to brand, high strategic value, have dev capacity | +| No-code tools (Outgrow, Typeform, Bubble) | Speed to market, limited dev resources, testing concept | +| Embed existing | Something good exists, white-label available, not core differentiator | + +--- + +## Evaluation Scorecard + +Rate each factor 1-5: + +| Factor | Score | +|--------|-------| +| Search demand exists | ___ | +| Audience match to buyers | ___ | +| Uniqueness vs. existing | ___ | +| Natural path to product | ___ | +| Build feasibility | ___ | +| Maintenance burden (inverse) | ___ | +| Link-building potential | ___ | +| Share-worthiness | ___ | + +**25+**: Strong candidate | **15-24**: Promising | **<15**: Reconsider + +--- + +## MVP Scope + +### Minimum Viable Tool +1. Core functionality only: does the one thing, works reliably +2. Essential UX: clear input, obvious output, mobile works +3. Basic lead capture: email collection, leads go somewhere useful + +### What to Skip Initially +Account creation, saving results, advanced features, perfect design, every edge case. diff --git a/content-strategy/references/lead-magnets.md b/content-strategy/references/lead-magnets.md new file mode 100644 index 0000000..95ff50b --- /dev/null +++ b/content-strategy/references/lead-magnets.md @@ -0,0 +1,126 @@ +# Lead Magnets + +Strategy for creating lead magnets that capture emails, generate qualified leads, and lead to product adoption. + +--- + +## Lead Magnet Principles + +1. **Solve a specific problem**: "How to write cold emails that get replies" > "Marketing guide" +2. **Match the buyer stage**: Awareness needs education, consideration needs evaluation, decision needs implementation. +3. **High perceived value, low time investment**: Should look worth paying for, consumable in under 30 minutes. +4. **Natural path to product**: Solves a problem your product also solves. +5. **Easy to consume**: One clear format, works on mobile, no special software required. + +--- + +## Lead Magnet Types + +| Type | Best For | Effort | Time to Create | +|------|----------|--------|----------------| +| Checklist | Quick wins, process steps | Low | 1-2 hours | +| Cheat sheet | Reference material, shortcuts | Low | 2-4 hours | +| Template (doc/spreadsheet/Notion) | Repeatable processes, workflows | Low-Med | 2-8 hours | +| Swipe file | Inspiration, examples | Medium | 4-8 hours | +| Ebook/guide | Deep education, authority | High | 1-3 weeks | +| Mini-course (email) | Education + nurture | Medium | 1-2 weeks | +| Mini-course (video) | Education + personality | High | 2-4 weeks | +| Quiz/assessment | Segmentation, engagement | Medium | 1-2 weeks | +| Webinar | Authority, live engagement | Medium | 1 week prep | +| Resource library | Ongoing value, return visits | High | Ongoing | + +--- + +## Matching Lead Magnets to Buyer Stage + +### Awareness Stage (Educate on the problem) + +| Format | Example | +|--------|---------| +| Checklist | "10-Point Website Audit Checklist" | +| Cheat sheet | "SEO Cheat Sheet for Beginners" | +| Ebook/guide | "The Complete Guide to Email Marketing" | +| Quiz | "What Type of Marketer Are You?" | + +### Consideration Stage (Help evaluate solutions) + +| Format | Example | +|--------|---------| +| Comparison template | "CRM Comparison Spreadsheet" | +| Assessment | "Marketing Maturity Assessment" | +| Case study collection | "5 Companies That 3x'd Their Pipeline" | +| Webinar | "How to Choose the Right Analytics Tool" | + +### Decision Stage (Help implement) + +| Format | Example | +|--------|---------| +| Template | "Ready-to-Use Sales Email Templates" | +| Free trial | "14-Day Free Trial" | +| Implementation guide | "Migration Checklist: Switch in 30 Minutes" | +| ROI calculator | "Calculate Your Savings" | + +--- + +## Gating Strategy + +| Approach | When to Use | Trade-off | +|----------|-------------|-----------| +| **Full gate** | High-value content, bottom-funnel | Max capture, lower reach | +| **Partial gate** | Preview + full version | Balance of reach and capture | +| **Ungated + optional** | Top-funnel education | Max reach, lower capture | +| **Content upgrade** | Blog post + bonus | Contextual, high-intent | + +### What to Ask For +- **Email only**: highest conversion, lowest friction +- **Email + name**: enables personalization, slight friction +- **Email + company/role**: better lead qualification, more friction +- **Multi-field**: only for high-value offers (webinars, demos) + +Rule of thumb: every extra field reduces conversion by 5-10%. + +--- + +## Landing Page Structure + +1. **Headline**: Clear benefit (what they'll get and why it matters) +2. **Preview/mockup**: Visual of the lead magnet +3. **What's inside**: 3-5 bullet points of key takeaways +4. **Social proof**: Download count, testimonials, logos +5. **Form**: Minimal fields, clear CTA button +6. **FAQ**: Address hesitations + +--- + +## Promotion & Distribution + +### Blog CTAs & Content Upgrades +- Add relevant CTAs within blog posts (inline, end-of-post) +- Post-specific content upgrades convert 2-5x better than generic sidebar CTAs + +### Social Media +- Share snippets and teasers from the lead magnet +- Create carousel posts from key points +- Use the lead magnet as the CTA in your bio/profile + +### Paid Promotion +- Facebook/Instagram lead ads for top-funnel lead magnets +- Google Ads for high-intent lead magnets (templates, tools) +- LinkedIn for B2B lead magnets +- Retarget blog visitors with lead magnet ads + +--- + +## Measuring Success + +| Metric | Benchmark | +|--------|-----------| +| Landing page conversion rate | 20-40% (warm traffic), 5-15% (cold) | +| Email engagement | 30-50% open, 2-5% click | +| Lead-to-customer rate | 1-5% (B2B) | + +### Lead Quality Signals +- Higher-than-average email engagement +- Leads progress to trial/demo at expected rates +- Low unsubscribe rate after delivery +- Leads match ICP demographics diff --git a/content-strategy/references/marketing-ideas.md b/content-strategy/references/marketing-ideas.md new file mode 100644 index 0000000..ee084e7 --- /dev/null +++ b/content-strategy/references/marketing-ideas.md @@ -0,0 +1,233 @@ +# Marketing Ideas for SaaS (139 Ideas Catalog) + +Proven marketing strategies organized by category. Use for brainstorming when stuck or exploring new growth channels. + +--- + +## Ideas by Category + +### Content & SEO (1-10) +1. Easy keyword ranking (low-competition long-tail) +2. Programmatic SEO at scale +3. Glossary marketing (define industry terms) +4. Content repurposing (one piece → many formats) +5. Guest posting on high-DA sites +6. Content partnerships and swaps +7. Original research and data reports +8. "Best of" roundup posts +9. FAQ content from support tickets +10. Interactive content (calculators, quizzes) + +### Competitor (11-13) +11. Comparison pages ("[You] vs [Competitor]") +12. Alternative pages ("[Competitor] alternatives") +13. Marketing jiu-jitsu (use competitors' weaknesses) + +### Free Tools (14-22) +14. Chrome extension +15. Engineering as marketing (free tool) +16. ROI calculator +17. Template library +18. Grader/audit tool +19. API or developer tool +20. Embeddable widget +21. Open-source project +22. Slack/Discord bot + +### Paid Ads (23-34) +23. Google Search Ads (high-intent) +24. Google Display remarketing +25. YouTube pre-roll ads +26. Facebook/Instagram awareness +27. Facebook/Instagram conversion +28. LinkedIn Ads (B2B targeting) +29. Twitter/X promoted posts +30. Podcast sponsorships +31. Google Ads (high-intent search) +32. Reddit Ads +33. Quora Ads +34. Retargeting across platforms + +### Social & Community (35-44) +35. Build a community (Slack, Discord, Circle) +36. LinkedIn personal brand +37. Twitter/X presence +38. Reddit marketing (authentic participation) +39. Short-form video (TikTok, Reels, Shorts) +40. Live streaming +41. Facebook Groups +42. Indie Hackers engagement +43. Hacker News presence +44. Comment marketing (valuable comments on relevant posts) + +### Email (45-53) +45. Welcome email sequence +46. Newsletter +47. Founder personal emails +48. Re-engagement campaigns +49. Lead nurture sequences +50. Product update emails +51. Win-back campaigns +52. Event-triggered emails +53. Digest emails (weekly/monthly roundups) + +### Partnerships (54-64) +54. Affiliate program +55. Referral program +56. Integration partnerships +57. Expert network partnerships +58. Co-marketing campaigns +59. Newsletter swaps +60. Webinar partnerships +61. Bundle deals +62. Reseller partnerships +63. Technology partnerships +64. Strategic advisory partnerships + +### Events (65-72) +65. Webinars +66. Virtual summits +67. Workshops +68. Meetups +69. AMA sessions +70. Conference speaking +71. Hackathons +72. Conference sponsorships + +### PR & Media (73-76) +73. Press coverage +74. Podcast appearances +75. Documentary/behind-the-scenes +76. Media acquisitions (buy a newsletter) + +### Launches (77-86) +77. Beta access campaigns +78. Product Hunt launch +79. Waitlist with referral mechanics +80. BetaList launch +81. Early access pricing +82. Lifetime deals (AppSumo, etc.) +83. Giveaways and contests +84. Hacker News Show HN +85. Launch on multiple platforms same week +86. Feature launch campaigns + +### Product-Led (87-96) +87. "Powered by" marketing +88. Viral invite mechanics +89. In-product sharing features +90. User-generated content +91. In-app upsells +92. Free migrations from competitors +93. Viral loops +94. Collaborative features (multiplayer) +95. Public dashboards/leaderboards +96. Free plan as marketing channel + +### Content Formats (97-109) +97. Podcast (own show) +98. YouTube channel +99. Online courses +100. Email courses +101. Books/ebooks +102. Annual industry reports +103. Year-in-review content +104. Book marketing +105. Infographics +106. Case studies +107. Podcast guest tours +108. Twitter Spaces / LinkedIn Audio +109. Micro-content (daily tips) + +### Unconventional (110-122) +110. Awards and recognition campaigns +111. Challenges (30-day, etc.) +112. Guerrilla marketing +113. Hand-written notes to customers +114. Billboards in tech hubs +115. Swag with viral potential +116. Customer advisory boards +117. Open salary/revenue transparency +118. Competitor customer poaching +119. Trolling competitors (tastefully) +120. Seasonal campaigns +121. Charity tie-ins +122. Micro-influencer campaigns + +### Platforms (123-130) +123. App marketplace listings +124. Review sites (G2, Capterra, TrustRadius) +125. YouTube SEO +126. Pinterest (for visual products) +127. Shopify App Store +128. WordPress plugin directory +129. Chrome Web Store +130. Slack App Directory + +### International (131-132) +131. International expansion +132. Price localization + +### Developer (133-136) +133. DevRel and developer marketing +134. Certification programs +135. Developer documentation as marketing +136. Open-source contributions + +### Audience-Specific (137-139) +137. Referral program optimization +138. Podcast guest tours +139. Customer language mining (use their words in your copy) + +--- + +## Prioritization by Stage + +### Pre-launch +- Waitlist referrals (#79) +- Early access pricing (#81) +- Product Hunt prep (#78) + +### Early stage (first customers) +- Content & SEO (#1-10) +- Community building (#35) +- Founder-led sales (#47) + +### Growth stage +- Paid acquisition (#23-34) +- Partnerships (#54-64) +- Events (#65-72) + +### Scale +- Brand campaigns +- International (#131-132) +- Media acquisitions (#73) + +--- + +## Prioritization by Budget + +| Budget | Best Categories | +|--------|----------------| +| Free | Content & SEO, Community, Social media, Comment marketing | +| Low | Targeted ads, Sponsorships, Free tools | +| Medium | Events, Partnerships, PR | +| High | Acquisitions, Conferences, Brand campaigns | + +--- + +## Using This List + +When recommending ideas: + +1. Ask about product, audience, and current stage if not clear +2. Suggest 3-5 most relevant ideas based on context +3. Provide implementation steps for chosen ideas +4. Consider resources (time, budget, team size) + +For each recommendation, provide: +- **Idea name**: One-line description +- **Why it fits**: Connection to their situation +- **How to start**: First 2-3 implementation steps +- **Expected outcome**: What success looks like +- **Resources needed**: Time, budget, skills required diff --git a/content-strategy/references/social-content.md b/content-strategy/references/social-content.md new file mode 100644 index 0000000..e755401 --- /dev/null +++ b/content-strategy/references/social-content.md @@ -0,0 +1,168 @@ +# Social Content Strategy + +Expert social media strategy: content pillars, hook formulas, platform-specific calendars, engagement routines, repurposing systems, and analytics. + +--- + +## 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 | + +--- + +## Content Pillars Framework + +Build content around 3-5 pillars that align with 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: +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]." + +--- + +## Content Repurposing System + +### 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 | + +### Repurposing Workflow + +1. Create pillar content (blog, video, podcast) +2. Extract key insights (3-5 per piece) +3. Adapt to each platform (format and tone) +4. Schedule across the week (spread distribution) +5. Update and reshare (evergreen content can repeat) + +--- + +## 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) + +### 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. + +--- + +## Reverse Engineering Viral Content + +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 diff --git a/copywriting/SKILL.md b/copywriting/SKILL.md new file mode 100644 index 0000000..b96f502 --- /dev/null +++ b/copywriting/SKILL.md @@ -0,0 +1,207 @@ +--- +name: copywriting +description: "Write or improve marketing copy for any surface: pages, ads, app stores, landing pages, TikTok/Meta scripts, push notifications, UGC. Combines page copy frameworks with direct response principles." +--- + +# Copywriting + +Expert conversion copywriter. Write marketing copy that is clear, compelling, and drives action. This skill covers both page copy (homepages, landing pages, pricing, features) and direct response (App Store, Google Ads, Meta/TikTok scripts, push notifications, email). + +## Before Writing + +Read `.agents/product-marketing-context.md` if it exists — it contains product name, audience, and brand voice. + +Gather this context (ask if not provided): + +### 1. Page Purpose +- What type of page or surface? (homepage, landing page, pricing, feature, about, ad, App Store) +- What is the ONE primary action you want visitors to take? + +### 2. Audience +- Who is the ideal customer? +- What problem are they trying to solve? +- What objections or hesitations do they have? +- What language do they use to describe their problem? + +### 3. Product/Offer +- What are you selling or offering? +- What makes it different from alternatives? +- What's the key transformation or outcome? +- Any proof points (numbers, testimonials, case studies)? + +### 4. Context +- Where is traffic coming from? (ads, organic, email) +- What do visitors already know before arriving? + +--- + +## Core Principles + +### Clarity Over Cleverness +If you have to choose between clear and creative, choose clear. + +### Benefits Over Features +Features: What it does. Benefits: What that means for the customer. + +### Specificity Over Vagueness +- Vague: "Save time on your workflow" +- Specific: "Cut your weekly reporting from 4 hours to 15 minutes" + +### Customer Language Over Company Language +Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets. + +### One Idea Per Section +Each section should advance one argument. Build a logical flow down the page. + +--- + +## Direct Response Copy Formula + +**Emotional Promise + Rational Explanation.** + +1. Open with what the customer *achieves* (not what the product does). Ship faster. Invest smarter. Feel calm. +2. Follow immediately with the rational "how": what the product actually does to deliver that promise. + +Mix with: stories (yours or customers'), testimonials, specific numbers. + +**What to cut:** +- Superlatives ("the best," "the fastest"): claim the outcome instead +- "Streamline" and "supercharge": say what actually happens +- Feature bullet lists over 5 items: pick your strongest 3 +- Writing about yourself: every "we" that can be a "you" should be a "you" + +--- + +## Writing Style Rules + +1. **Simple over complex**: "Use" not "utilize," "help" not "facilitate" +2. **Specific over vague**: Avoid "streamline," "optimize," "innovative" +3. **Active over passive**: "We generate reports" not "Reports are generated" +4. **Confident over qualified**: Remove "almost," "very," "really" +5. **Show over tell**: Describe the outcome instead of using adverbs +6. **Honest over sensational**: Fabricated statistics erode trust and create legal liability + +--- + +## Page Structure Framework + +### Above the Fold + +**Headline**: Your single most important message. Communicate core value proposition. + +Example formulas: +- "{Achieve outcome} without {pain point}" +- "The {category} for {audience}" +- "Never {unpleasant event} again" + +**Subheadline**: Expands on headline, adds specificity, 1-2 sentences max. + +**Primary CTA**: Action-oriented. "Start Free Trial" > "Sign Up" + +For comprehensive headline formulas and page templates, see `references/copy-frameworks.md`. +For natural transition phrases, see `references/natural-transitions.md`. + +### Core Sections + +| Section | Purpose | +|---------|---------| +| Social Proof | Build credibility (logos, stats, testimonials) | +| Problem/Pain | Show you understand their situation | +| Solution/Benefits | Connect to outcomes (3-5 key benefits) | +| How It Works | Reduce perceived complexity (3-4 steps) | +| Objection Handling | FAQ, comparisons, guarantees | +| Final CTA | Recap value, repeat CTA, risk reversal | + +--- + +## CTA Copy Guidelines + +**Weak CTAs (avoid):** Submit, Sign Up, Learn More, Click Here, Get Started + +**Strong CTAs (use):** Start Free Trial, Get [Specific Thing], See [Product] in Action, Create Your First [Thing], Download the Guide + +**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed] + +--- + +## Page-Specific Guidance + +### Homepage +Serve multiple audiences without being generic. Lead with broadest value proposition. Provide clear paths for different visitor intents. + +### Landing Page +Single message, single CTA. Match headline to ad/traffic source. Complete argument on one page. + +### Pricing Page +Help visitors choose the right plan. Address "which is right for me?" anxiety. Make recommended plan obvious. + +### Feature Page +Connect feature → benefit → outcome. Show use cases and examples. Clear path to try or buy. + +### About Page +Tell the story of why you exist. Connect mission to customer benefit. Still include a CTA. + +--- + +## Best Practices + +### Be Direct +Get to the point. Don't bury the value in qualifications. + +### Use Rhetorical Questions +Questions engage readers: "Hate returning stuff to Amazon?" "Tired of chasing approvals?" + +### Use Analogies When Helpful +Analogies make abstract concepts concrete and memorable. + +--- + +## Output Format + +### Page Copy +Organized by section: Headline, Subheadline, CTA, section headers, body copy, secondary CTAs. + +### Annotations +For key elements, explain why you made this choice. + +### Alternatives +For headlines and CTAs, provide 2-3 options with rationale. + +--- + +## References + +This skill's reference files cover both page copy frameworks and direct response: + +### Page Copy +- [Copy Frameworks](references/copy-frameworks.md): Headline formulas, page section types, structural templates +- [Natural Transitions](references/natural-transitions.md): Transitional phrases for readable content +- [Direct Response Frameworks](references/direct-response-frameworks.md): Extended direct response formulas, long-form copy structures, classic frameworks + +### Direct Response +- [Direct Response Principles](references/direct-response-principles.md) +- [Brand Voice Reference](references/brand-voice-reference.md) +- [Platform Character Limits](references/platform-character-limits-reference.md) +- [1. App Store Descriptions](references/1-app-store-descriptions.md) +- [2. Google Ads](references/2-google-ads.md) +- [3. Landing Pages](references/3-landing-pages.md) +- [4. TikTok / Meta Ad Scripts](references/4-tiktok-meta-ad-scripts.md) +- [5. Push Notifications](references/5-push-notifications.md) +- [6. Email Sequences](references/6-email-sequences.md) +- [7. UGC Script Templates](references/7-ugc-script-templates.md) +- [Quiz Funnel Copy](references/quiz-funnel-copy.md) +- [A/B Testing Framework](references/a-b-testing-framework.md) +- [Copy Anti-Patterns](references/copy-anti-patterns-kill-on-sight.md) +- [Real-World Examples](references/real-world-examples-finance-investing-apps.md) +- [The Seven Sweeps](references/the-seven-sweeps-copy-editing-framework.md) +- [Process: Writing Copy](references/process-writing-copy-with-this-skill.md) +- [CTA Library](references/quick-reference-cta-library.md) + +--- + +## Related Skills + +- **evaluate-content**: For polishing and evaluating copy (seven sweeps, six questions) +- **growth**: For page CRO, signup flow, paywall optimization +- **content-strategy**: For content planning and topic selection +- **marketing-psychology**: For persuasion principles in copy diff --git a/copywriting/references/1-app-store-descriptions.md b/copywriting/references/1-app-store-descriptions.md new file mode 100644 index 0000000..81f76f9 --- /dev/null +++ b/copywriting/references/1-app-store-descriptions.md @@ -0,0 +1,192 @@ +# 1. App Store Descriptions + +App Store copy is the highest-leverage copy you can write. Every ad, every link, every mention ultimately drives to this page. If the listing doesn't convert, everything upstream is wasted. + +### iOS App Store + +#### App Name (30 characters) + +The name is your #1 ranking factor and your #1 brand signal. Use it wisely. + +**Formula**: `[Brand Name]: [Core Value Prop]` or `[Brand Name] - [Key Benefit]` + +``` +✅ Bloom: Stock Research & AI (28 chars) +✅ Bloom - AI Investing Research (30 chars) +✅ Bloom: AI Stock Analysis (25 chars) + +❌ Bloom (wastes keyword space) +❌ Bloom - The Best AI-Powered... (truncated, looks broken) +❌ Bloom Investing Research AI App (keyword stuffing) +``` + +**Finance/investing app examples that convert:** +- `Robinhood: Investing for All` (28 chars) +- `Webull: Investing & Trading` (27 chars) +- `Seeking Alpha: Stock Market` (27 chars) +- `Morningstar: Investing` (22 chars) + +#### Subtitle (30 characters) + +Reinforces the name with a benefit. Not a feature restatement. + +``` +✅ Research Stocks in Seconds (27 chars) ← benefit + speed +✅ Smarter Stock Research (23 chars) ← benefit +✅ AI-Powered Stock Analysis (26 chars) ← method + what + +❌ Trading & Investing App (generic, no benefit) +❌ Best Stock Market App (claim without proof) +❌ For Investors & Traders (audience, not benefit) +``` + +#### Keyword Field (100 characters) + +Comma-separated. No spaces after commas. Don't repeat words from your name or subtitle (Apple already indexes those). + +``` +stocks,investing,portfolio,trading,analyst,ratings,earnings,research, +finance,market,AI,screener,alerts,dividends,options +``` + +**Rules:** +- Don't waste characters on your app name or competitor names (against guidelines) +- Singular > plural (Apple matches both) +- No spaces after commas (wastes characters) +- Test different keyword combos monthly using Appfigures/App Annie rank tracking +- Prioritize high-volume, medium-competition keywords + +#### Description (4,000 characters) + +Only the first 3 lines (~90 characters) are visible before "more." These 3 lines are your entire pitch for 80% of viewers. + +**Structure:** + +``` +LINE 1-3 (above the fold — this is everything): +[Benefit-driven hook that makes them tap "more"] + +"Research any stock in 30 seconds. Bloom uses AI to break down analyst +ratings, insider trades, earnings, and catalysts — so you make smarter +investment decisions without spending hours reading filings." + +REST OF DESCRIPTION: + +WHY INVESTORS CHOOSE BLOOM +• AI stock research covering 6,000+ tickers +• Real-time analyst rating changes and price targets +• Insider trading alerts (see what executives are buying) +• Earnings breakdowns with AI-generated summaries +• Smart watchlist with custom alerts + +HOW IT WORKS +1. Search any stock or add it to your watchlist +2. Get an instant AI breakdown: bull case, bear case, key metrics +3. Receive alerts when something changes (analyst upgrade, insider buy, earnings beat) + +WHAT MAKES BLOOM DIFFERENT +Unlike stock screeners that give you raw data, Bloom explains what the data means. Our AI reads 10-K filings, earnings transcripts, and analyst reports — then gives you the insight in plain English. + +"I found a 40% undervalued stock in my first week using Bloom." +— App Store review, ★★★★★ + +WHAT'S INCLUDED FREE +✓ AI research for any stock +✓ Watchlist with alerts +✓ Earnings calendar +✓ Basic analyst ratings + +BLOOM PREMIUM +✓ Unlimited AI research conversations +✓ Real-time insider trading data +✓ Advanced screeners and filters +✓ Priority alerts + +Download Bloom. Research your first stock in 60 seconds. +``` + +**Rules:** +- First 3 lines must stand alone as a complete pitch +- Use line breaks aggressively. Walls of text don't get read. +- Bullet points > paragraphs for features +- One user quote with stars. Specificity > effusiveness. +- End with a CTA. "Download Bloom" not "We hope you enjoy our app!" +- Don't use the description for keyword stuffing. iOS doesn't index it. +- Update quarterly. Test different above-fold hooks. + +#### What's New (4,000 characters) + +Most apps waste this with "bug fixes and performance improvements." That's a missed conversion opportunity. + +``` +✅ GOOD: +NEW: AI earnings analysis +Bloom now breaks down earnings reports in real-time. Get the bull case, bear +case, and key surprises within minutes of the announcement. + +Also in this update: +• Faster stock search (2x improvement) +• New insider trading alerts +• Fixed notification delivery on iOS 18 + +❌ BAD: +Bug fixes and performance improvements. +``` + +**Rules:** +- Lead with the most exciting new feature +- Name the specific benefit, not just the feature name +- Include 2-3 smaller improvements as bullets +- This appears on the update screen. It's a re-engagement opportunity. + +#### Screenshot Text + +Screenshots are your most powerful conversion tool. First 3 are visible in search results. + +**Rules:** +- Screenshot 1 = your best pitch (most people only see this one) +- Text on screenshots should be benefits, not feature names +- Max 5-7 words per screenshot overlay +- Show real app UI, not mockups + +``` +Screenshot 1: "Research Any Stock in 30 Seconds" +Screenshot 2: "AI Reads the Filings. You Get the Insight." +Screenshot 3: "Real-Time Analyst Upgrades & Downgrades" +Screenshot 4: "See What Insiders Are Buying" +Screenshot 5: "Earnings Breakdowns in Plain English" +Screenshot 6: "Smart Alerts. Never Miss a Move." +``` + +**Anti-patterns:** +- ❌ "Powerful AI Technology" (means nothing) +- ❌ "Beautiful Interface" (obvious/subjective) +- ❌ "Feature 1, Feature 2, Feature 3" (list dump) +- ❌ Microscopic text that's unreadable on phone screens + +### Google Play Store + +Google Play's description IS indexed for search. This changes everything. + +#### Short Description (80 characters) + +This is your App Store subtitle equivalent but with nearly 3x the space. Use it. + +``` +✅ AI stock research: analyst ratings, insider trades, earnings. All in one app. (79 chars) +✅ Research any stock in 30 seconds with AI. Free to download. (65 chars) + +❌ The best investing app for stock market research (generic) +❌ Bloom is an AI-powered investing research platform (feature, not benefit) +``` + +#### Full Description (4,000 characters) + +Unlike iOS, Google Play DOES index the description for keyword ranking. Weave in keywords naturally, but don't stuff. Google penalizes keyword stuffing. + +**Structure is the same as iOS** but add keyword variations: +- "stock research" and "stock analysis" and "investing research" +- "analyst ratings" and "analyst upgrades" and "price targets" +- Natural keyword density: 2-3% per target keyword + +--- diff --git a/copywriting/references/2-google-ads.md b/copywriting/references/2-google-ads.md new file mode 100644 index 0000000..92e768d --- /dev/null +++ b/copywriting/references/2-google-ads.md @@ -0,0 +1,144 @@ +# 2. Google Ads + +Every character costs money. Literally. Bad copy = higher CPC, lower quality score, wasted budget. + +### Responsive Search Ads (RSA) + +Google tests combinations of your headlines and descriptions. Give it good ingredients. + +#### Headlines (30 characters each, up to 15) + +Write headlines in tiers: + +**Tier 1: Benefit headlines (write 5)** +``` +Research Stocks in Seconds (26) +AI Stock Research App (21) +Free Stock Analysis Tool (24) +See Why Stocks Move (19) +Never Miss an Upgrade (22) +``` + +**Tier 2: Proof/trust headlines (write 3)** +``` +4.8★ Rating, 2,400+ Reviews (28) +52,000+ Investors Use Bloom (27) +Free Download, No Card Needed (30) +``` + +**Tier 3: CTA headlines (write 3)** +``` +Download Bloom Free (19) +Start Investing Smarter (23) +Try Bloom - It's Free (20) +``` + +**Tier 4: Keyword-match headlines (write 4)** +``` +AI Investing Research (21) +Stock Research Made Simple (26) +Best Stock Analysis App (23) +Analyst Ratings & Alerts (24) +``` + +**Rules:** +- Pin your strongest benefit headline to Position 1 +- Pin your strongest CTA to Position 3 +- Let Google test the rest +- No two headlines should say the same thing differently +- Include the primary keyword in at least 3 headlines +- Use Title Case (Google standard) + +#### Descriptions (90 characters each, up to 4) + +``` +Description 1 (benefit + proof): +"Research any stock in 30 seconds. AI-powered analysis used by 52,000+ investors." (82) + +Description 2 (how it works): +"Get analyst ratings, insider trades, and earnings breakdowns. All in one free app." (83) + +Description 3 (risk reversal): +"Free to download. No credit card. Cancel premium anytime. Start in under a minute." (84) + +Description 4 (differentiator): +"Unlike screeners, Bloom explains what the data means. AI reads filings for you." (81) +``` + +**Rules:** +- Description 1 should work alone (it's shown most often) +- Include a CTA in at least one description +- Include social proof in at least one description +- Don't repeat headline copy in descriptions + +#### Performance Max Asset Groups + +Performance Max needs more creative variation. Supply: + +| Asset Type | Quantity | Bloom Examples | +|-----------|----------|----------------| +| Headlines (30 char) | 5 min | Same RSA headlines | +| Long headlines (90 char) | 5 min | "Research Any Stock in 30 Seconds with AI-Powered Analysis. Download Free." | +| Descriptions (90 char) | 4 min | Same RSA descriptions | +| Business name | 1 | "Bloom" | +| Call to action | 1 | "Download" or "Get offer" | +| Images | 3+ (1200x628, 960x960, 480x600) | App screenshots, results, UI | +| Videos | 1+ (landscape + vertical) | Same as TikTok/Meta scripts | +| Final URL | 1 | App Store / landing page URL | + +#### Display URL Paths (15 characters each) + +``` +getbloom.app/Stock/Research ← tells them what they'll find +getbloom.app/AI/Investing ← keyword reinforcement +getbloom.app/Free/Download ← risk reversal in the URL +``` + +#### Ad Extensions (use all of them) + +**Sitelinks (25 char title + 35 char description × 2):** +``` +Title: "AI Stock Research" +Desc 1: "Search 6,000+ tickers instantly." +Desc 2: "AI reads the filings for you." + +Title: "Real-Time Alerts" +Desc 1: "Analyst upgrades. Insider buys." +Desc 2: "Never miss a move on your stocks." + +Title: "Free to Download" +Desc 1: "No credit card required." +Desc 2: "Research your first stock in 60s." + +Title: "See App Reviews" +Desc 1: "4.8★ average from 2,400+ ratings." +Desc 2: "Investors love Bloom's AI research." +``` + +**Callouts (25 characters):** +``` +Free to Download +AI-Powered Research +6,000+ Stocks Covered +Real-Time Analyst Alerts +No Credit Card Needed +4.8★ App Store Rating +``` + +**Structured Snippets:** +``` +Type: Features +Values: AI Research, Analyst Ratings, Insider Trades, Earnings Analysis, Smart Alerts, Watchlists +``` + +### Google Ads Quality Score Rules + +Quality Score directly affects your CPC. Higher score = lower cost per click. + +1. **Ad relevance**: Headlines must contain the keyword the ad group targets +2. **Landing page experience**: The page must deliver on the ad's promise +3. **Expected CTR**: Specific, benefit-driven copy gets more clicks + +**The #1 mistake:** Writing one ad that targets every keyword. Write ad groups around tight keyword themes. "AI stock research" ads and "analyst rating alerts" ads need different copy. + +--- diff --git a/copywriting/references/3-landing-pages.md b/copywriting/references/3-landing-pages.md new file mode 100644 index 0000000..8c77288 --- /dev/null +++ b/copywriting/references/3-landing-pages.md @@ -0,0 +1,152 @@ +# 3. Landing Pages + +A landing page has one job: convert visitors into users. One page, one CTA, one action. + +### Structure (top to bottom) + +#### Hero Section + +``` +HEADLINE (8-12 words): +"Research Any Stock in 30 Seconds" + +SUBHEADLINE (15-25 words): +"Bloom uses AI to break down analyst ratings, insider trades, and earnings. +52,000 investors already use it." + +CTA BUTTON: +"Download Free" (primary) +"See How It Works" (secondary, for non-ready visitors) + +VISUAL: +App screenshot showing real stock analysis (NOT a mockup, NOT an abstract illustration) +``` + +**Hero rules:** +- Headline = biggest benefit, not product name +- Subheadline = how it works + social proof +- CTA above the fold. Always. +- Show the product. People want to see what they're getting. + +#### Problem Section + +``` +HEADER: "Researching Stocks Shouldn't Take Hours" + +You're juggling Yahoo Finance, SEC filings, Reddit threads, and CNBC alerts. +By the time you piece it all together, the move already happened. + +[Visual: cluttered multi-tab browser screenshot vs. clean Bloom UI] +``` + +Name the specific pain. "Investing is hard" is not a problem statement. "You're checking 6 sources to make one decision" is. + +#### Solution Section + +``` +HEADER: "One Screen. Every Insight." + +Bloom reads the filings, tracks the analysts, monitors insider trades, and +summarizes it all in plain English. + +FEATURE BLOCKS (3 max, benefit-first): +1. "30-Second Research" — Search any stock, get the full picture instantly +2. "Real-Time Alerts" — Analyst upgrades, insider buys, earnings surprises +3. "AI That Cites Sources" — Not a black box. See exactly where insights come from. +``` + +**Rules:** +- 3 features max. More than 3 is a feature dump, not a value prop. +- Each feature = benefit headline + one-sentence explanation +- Benefit first, feature second: "Research in 30 seconds" (benefit) using "AI-powered analysis" (feature) + +#### Social Proof Section + +``` +HEADER: "52,000 Investors Already Use Bloom" + +★★★★★ "I found a 40% undervalued stock in my first week." +— @InvestorMike, App Store review + +★★★★★ "Replaced Yahoo Finance, Seeking Alpha, and 3 other apps." +— @SarahK, App Store review + +★★★★★ "The AI actually explains WHY a stock is moving. Not just that it moved." +— @TraderJohn, App Store review + +[App Store badge: 4.8★ from 2,400+ ratings] +[As featured in: TechCrunch, Product Hunt #1] +``` + +**Rules:** +- Real reviews only. Fake testimonials are illegal and detectable. +- Specific results > general praise. "Found a 40% undervalued stock" > "Great app!" +- Include name/handle for credibility +- Show aggregate rating (4.8★) for quick scanning +- 3 testimonials is the sweet spot. More = diminishing returns. + +#### Objection Handling + +Address the top 3-5 reasons someone would NOT convert. Put these below social proof. + +``` +"Is it really free?" +Yes. Download and basic research are completely free. No credit card required. +Premium unlocks unlimited AI conversations and advanced alerts. + +"Is the AI actually good?" +Bloom's AI cites its sources. Every insight links back to the filing, transcript, +or data point it came from. No hallucinated financial advice. + +"I already use [competitor]." +Bloom isn't a replacement for your brokerage. It's a research layer that makes +every platform better. Use Bloom to research, use your broker to trade. + +"Is my data safe?" +Bloom doesn't access your brokerage accounts. Read-only market data. Your +portfolio data stays on your device. +``` + +#### CTA Section (Bottom) + +``` +HEADER: "Research Your First Stock in 60 Seconds" + +[CTA Button: "Download Free"] + +Free. No credit card. Available on iOS and Android. +``` + +Repeat the CTA at the bottom. Many people scroll the entire page before deciding. Give them an easy action at every scroll depth. + +#### Pricing Section (if applicable) + +``` +FREE PREMIUM ($X/month) +✓ AI research (5/day) ✓ Unlimited AI research +✓ Basic watchlist ✓ Advanced screeners +✓ Earnings calendar ✓ Real-time insider data +✓ Market news ✓ Priority alerts + ✓ Full analyst rating history + + [Start Free] [Go Premium] +``` + +**Rules:** +- Free tier should feel generous, not crippled +- Premium should feel like a clear upgrade, not a necessity +- Anchor price against competitors: "Less than one Seeking Alpha subscription" +- If offering a trial: "14-day free trial. Cancel in one tap." + +### Landing Page Anti-Patterns + +- ❌ Multiple CTAs competing for attention (pick ONE primary action) +- ❌ Navigation menu with links away from the page (remove nav on landing pages) +- ❌ Stock photos of smiling people pointing at phones +- ❌ Feature lists with no benefits attached +- ❌ "Learn More" as CTA text (learn more about what? be specific) +- ❌ Walls of text with no visual breaks +- ❌ Pop-ups that appear before the visitor has read anything +- ❌ No social proof anywhere on the page + +--- diff --git a/copywriting/references/4-tiktok-meta-ad-scripts.md b/copywriting/references/4-tiktok-meta-ad-scripts.md new file mode 100644 index 0000000..13f212f --- /dev/null +++ b/copywriting/references/4-tiktok-meta-ad-scripts.md @@ -0,0 +1,231 @@ +# 4. TikTok / Meta Ad Scripts + +Video ads follow a strict rhythm. Every second is earned. + +### The Universal Ad Script Structure + +``` +HOOK (0-3 seconds) — Stop the scroll. Pattern interrupt. +PROBLEM (3-8 seconds) — Name their pain. Be specific. +SOLUTION (8-18 seconds)— Show the product solving the problem. +PROOF (18-23 seconds) — Social proof, results, credibility. +CTA (23-30 seconds) — Tell them exactly what to do. +``` + +Total: 25-30 seconds for conversion ads. Shorter is better. If you can do it in 15 seconds, do it in 15 seconds. + +### Script Templates + +#### Template 1: "I Found the Thing" (Personal Discovery) + +``` +HOOK (0-2s): +[Text overlay: "The app Wall Street doesn't want you to have"] +[Voice]: "I've been using this one app for all my stock research..." + +PROBLEM (2-7s): +"I used to spend HOURS reading analyst reports and SEC filings. +Yahoo Finance, Seeking Alpha, Reddit, earnings transcripts... +by the time I had a thesis, the stock already moved." + +SOLUTION (7-17s): +"Then I found Bloom. You search any stock and it gives you +EVERYTHING: analyst ratings, insider trades, earnings breakdowns, +bull case, bear case. In like 30 seconds." +[Show app UI: search stock → AI analysis appearing] + +PROOF (17-22s): +"It's got a 4.8 star rating. 52,000 investors use it. +And the AI actually shows you WHERE it got the information." + +CTA (22-27s): +"It's free to download. Link is in my bio." +[Text overlay: "Download Bloom — Free"] +``` + +#### Template 2: "Did You Know?" (Information Gap) + +``` +HOOK (0-2s): +[Text overlay: "90% of investors miss this"] +[Voice]: "Did you know you can see exactly what company insiders +are buying and selling?" + +PROBLEM (2-6s): +"CEOs and board members buy their own stock before it goes up. +It's all public data. But most people don't know where to find it." + +SOLUTION (6-16s): +"This app is called Bloom. It tracks every insider trade and +sends you an alert when an executive makes a big buy." +[Show app: insider trading screen with real data] + +PROOF (16-20s): +"Last month it flagged three stocks where insiders were loading up. +All three are up double digits." + +CTA (20-25s): +"Free download, link in bio." +[Text overlay: "Bloom — Free Stock Research"] +``` + +#### Template 3: "Hot Take / Contrarian" (Opinion-Led) + +``` +HOOK (0-2s): +[Text overlay: "Unpopular opinion"] +[Voice]: "If you're still using Yahoo Finance for stock research, +you're doing it wrong." + +PROBLEM (2-6s): +"Yahoo gives you a wall of numbers with no context. +You still have to figure out what it all means yourself." + +SOLUTION (6-15s): +"There's this AI app that actually EXPLAINS the numbers. +You search Tesla and it tells you: here are the 3 reasons analysts +are bullish, here's the bear case, here's what insiders are doing." +[Show app UI] + +PROOF (15-19s): +"4.8 stars. Over 50,000 investors." + +CTA (19-23s): +"Download Bloom free. Link in bio." +``` + +#### Template 4: "Screen Recording" (Product Demo) + +``` +HOOK (0-2s): +[Screen recording starting mid-action] +[Text overlay: "How I research stocks in 30 seconds"] + +DEMO (2-20s): +[Record actual app usage]: +- Open Bloom +- Search "NVDA" +- Show AI analysis loading +- Scroll through analyst ratings +- Show insider trading data +- Show earnings breakdown + +[Voice over the recording]: +"Search any stock. Boom — full AI breakdown. Analyst ratings +right here. Insider trades. Earnings surprises. +This would've taken me an hour on Yahoo Finance." + +CTA (20-25s): +"App is called Bloom. Free download." +[Text overlay: "Bloom — Link in Bio"] +``` + +### Viral Hook Principles (validated: 18M views, zero audience, zero budget) + +These four rules override any template when there's a conflict. A solo dev applied them to get 18M YouTube Shorts views in 28 days from scratch. + +**1. The hook is about the viewer, not the product.** +Every ad that flops opens with the product's features. Every ad that goes viral opens with something the viewer experiences, fears, wants, or wonders about themselves. +- ❌ "Bloom's AI analyzes every stock for you" (about the product) +- ✅ "I let an AI pick my stocks for 30 days and I wasn't ready for what it found" (about the experience) + +**2. Broad angle > niche angle.** +"Investing app" reaches investors. "What if you could see what hedge funds buy before it hits the news" reaches anyone with money. Find the universal human experience (FOMO, insider edge, outsmarting the system, proving someone wrong) that your product connects to. + +**3. Build a curiosity gap — tease early, reveal late.** +Introduce a question or result in the first 3 seconds that you don't answer until the final seconds. People don't stay for the product — they stay because they need the answer. The app demo is just something to look at while they wait. +- Bad: Reveal the stock pick in second 5, then explain it for 25 seconds. +- Good: "This AI bought a stock I would never have touched. Here's what happened." → Show the analysis → reveal the result at 25 seconds. + +**4. Every line earns the next.** +If a line explains or teaches without escalating tension, cut it. Information is the reward at the end, not the scaffolding. Read the script line by line — each line should make the viewer more curious, not more informed (until the end). + +--- + +### TikTok-Specific Rules + +1. **Vertical video only** (9:16). No letterboxing. +2. **Text on screen from frame 1.** Audio might be off. +3. **No logos in the first 3 seconds.** It signals "ad" and gets skipped. +4. **Native feel > polished.** Film on phone, not studio. Talk to camera, not at camera. +5. **The hook IS the ad.** If the first 2 seconds don't land, nothing else matters. +6. **Music/trending sound under the voiceover.** Boosts distribution. +7. **CTA = "Link in bio"** (TikTok doesn't support clickable links in organic, only Spark Ads or paid). + +### Meta (Facebook/Instagram) Specific Rules + +1. **Square (1:1) or vertical (4:5) for feed.** 9:16 for Stories/Reels. +2. **Design for sound-off.** Captions/text overlays on all dialogue. +3. **First 3 seconds must work as a static image** (feed autoplay is often paused). +4. **CTA button text matters.** "Download" converts better than "Learn More" for apps. +5. **Carousel ads**: Each card = one benefit. Card 1 = hook. Last card = CTA. + +#### Template 5: "Emotional Arc" (5-Beat Progression) + +Longer-form video (30-35s) with deliberate energy shifts that mirror how real people talk about discoveries. Each beat has a distinct emotional tone. + +``` +BEAT 1: CURIOSITY (0-5s) — Moderate energy, conversational +"okay so I need to tell you about something I just found" +[Lean forward slightly. Interest, not hype. Approachable.] + +BEAT 2: FRUSTRATION (5-12s) — Energy dips, relatable pain +"because honestly I was spending hours reading analyst reports +and by the time I had a thesis, the stock already moved" +[Slight head shake. Slower pace. Authentic disappointment.] + +BEAT 3: DISCOVERY (12-20s) — Energy builds, genuine excitement +"then I found this app and literally within the first search +I got a full AI breakdown: bull case, bear case, insider trades" +[Show app UI. Brightening expression. Faster pace.] + +BEAT 4: VALIDATION (20-28s) — Peak energy, confidence +"like it's showing me what company CEOs are buying before +the stock moves, and it cites every source so I can verify" +[Animated hand gestures. Direct eye contact. This is the proof.] + +BEAT 5: RECOMMENDATION (28-35s) — Warm, direct, slightly lower +"if you do any kind of stock research, just try it. +it's called Bloom. free download. you can thank me later" +[Friendly but confident. Natural conclusion, not a hard sell.] +``` + +**Why the arc matters:** Flat energy = fake. Real testimonials have emotional dynamics. The dip at beat 2 makes the excitement at beats 3-4 feel earned. The slight cooldown at beat 5 signals authenticity (hard sells stay at peak energy, which viewers have learned to distrust). + +**Adaptation for shorter formats (15-20s):** Collapse beats 1+2 into a single "problem hook" (0-5s) and beats 4+5 into "proof + CTA" (15-20s). Keep beat 3 (discovery) as the core. + +### Video Ad Anti-Patterns + +- ❌ Starting with your logo or brand name (instant skip) +- ❌ "Hey guys, so today I want to talk about..." (zero hook) +- ❌ Background music louder than voice +- ❌ Cramming 10 features into 30 seconds (pick 2-3) +- ❌ Professional studio lighting for organic-style content (feels like an ad) +- ❌ Showing the app for more than 15 seconds without voiceover context +- ❌ Ending without a CTA +- ❌ "Check it out" as a CTA (check WHAT out WHERE?) + +--- + +### Geo-Targeted Ads: Regional Localization + +When running Meta paid ads to specific regional markets (city/radius targeting), localize the script — not just the targeting. Same product, different frame. + +**Three elements to adapt per regional variant:** + +1. **Industry context in the hook** — reference dominant local industry in the problem beat + - Memphis → logistics, distribution, supply chain + - Nashville → healthcare, insurance, medical admin + - Richmond → financial services, insurance + - Boise → independent retail, service businesses + - Phoenix → construction, real estate, professional services + +2. **Business size framing** — regional markets skew smaller teams; adjust "person like me" framing + - "managing a team of 8 to 15 people" > generic professional framing + +3. **Tone register** + - Southern markets: warmer, relationship-oriented, less efficiency jargon + - Northern/western: direct, outcome-first, efficiency-focused + - Midwest: practical, skeptical of hype + +**Production:** With AI UGC (see `references/7-ugc-script-templates.md`), regional variants are near-zero marginal effort — adapt hook + framing + tone, regenerate voice, redeploy. Test 8-12 markets simultaneously, concentrate paid budget on organic traction winners. diff --git a/copywriting/references/5-push-notifications.md b/copywriting/references/5-push-notifications.md new file mode 100644 index 0000000..311d1d9 --- /dev/null +++ b/copywriting/references/5-push-notifications.md @@ -0,0 +1,76 @@ +# 5. Push Notifications + +Push notifications are the highest-converting channel you have. They're also the fastest way to get uninstalled. Respect them. + +### Rules + +1. **Every push must deliver value or trigger action.** No "We miss you!" garbage. +2. **Personalize.** "NVDA just got upgraded to Buy" > "Check out new analyst ratings" +3. **Timing matters.** Market hours for market events. Never push at 3 AM. +4. **Frequency cap.** Max 1-2/day for engaged users. Max 2-3/week for casual users. +5. **Deep link to the relevant screen.** Don't push about insider trades and drop them on the home screen. + +### Templates by Type + +#### Trigger-Based (Highest Value) + +Fired by real events on stocks the user watches. + +``` +ANALYST UPGRADE: +Title: "NVDA Upgraded to Buy" +Body: "Goldman Sachs upgraded NVIDIA with a $180 price target. See the full analysis." + +INSIDER TRADE: +Title: "AAPL CEO just bought $10M in stock" +Body: "Tim Cook purchased 50,000 shares at $198. Largest insider buy this quarter." + +EARNINGS BEAT: +Title: "TSLA beat earnings by 15%" +Body: "Revenue $25.7B vs $24.2B expected. AI breaks down the call highlights." + +PRICE ALERT: +Title: "AMZN hit your $200 target" +Body: "Amazon crossed $200 for the first time since March. Tap to see what changed." +``` + +#### Feature Announcements + +``` +NEW FEATURE: +Title: "New: AI Earnings Analysis" +Body: "Bloom now breaks down earnings calls in real-time. Try it with AAPL's report tonight." + +IMPROVEMENT: +Title: "Stock search is 2x faster" +Body: "We rebuilt search from scratch. Try it — search any of 6,000+ tickers." +``` + +#### Re-engagement + +Only send after 7+ days of inactivity. Require a hook. + +``` +MARKET EVENT: +Title: "Markets dropped 3% today" +Body: "Your watchlist has 4 stocks down over 5%. Tap to see which analysts are upgrading." + +MISSED ALERT: +Title: "2 stocks on your watchlist got upgraded" +Body: "While you were away, MSFT and GOOGL received analyst upgrades. See details." + +SEASONAL: +Title: "Earnings season starts Monday" +Body: "243 companies report this week, including 3 on your watchlist. Set your alerts." +``` + +#### Push Anti-Patterns + +- ❌ "We miss you! Come back!" (guilt trip, zero value) +- ❌ "Check out what's new in Bloom" (what IS new? be specific) +- ❌ "Investing tip of the day" (unsolicited, not personalized) +- ❌ Pushing the same message to all users (segment or don't push) +- ❌ More than 3 pushes in a day (instant uninstall territory) +- ❌ Pushing at 2 AM about non-urgent features + +--- diff --git a/copywriting/references/6-email-sequences.md b/copywriting/references/6-email-sequences.md new file mode 100644 index 0000000..f41a57b --- /dev/null +++ b/copywriting/references/6-email-sequences.md @@ -0,0 +1,253 @@ +# 6. Email Sequences + +Email is the workhorse of conversion. Not for newsletters (that's content marketing). These are action-driving sequences tied to specific user lifecycle stages. + +### Welcome Sequence (Post-Download, 5 emails over 10 days) + +**Email 1: Immediate (within 5 minutes of download)** + +``` +Subject: Your first stock research is waiting (26 chars + emoji optional) +Preview: Search any stock and get an instant AI breakdown + +Body: +Welcome to Bloom. + +Here's how to get your first insight in 60 seconds: + +1. Open the app +2. Search any stock (try one you own) +3. Read the AI breakdown: bull case, bear case, key metrics + +That's it. You just did in 30 seconds what used to take 30 minutes. + +[CTA Button: "Open Bloom"] + +— Eric, Founder + +P.S. Reply to this email if you have questions. I read every one. +``` + +**Email 2: Day 2 (Feature highlight)** + +``` +Subject: The feature 90% of new users miss +Preview: Most people don't set this up and regret it + +Body: +Most Bloom users don't set up alerts until after they miss a big move. + +Set up a watchlist alert in 20 seconds: +1. Add stocks to your watchlist +2. Tap the bell icon on any stock +3. Choose: analyst upgrades, insider trades, earnings, or price targets + +Last week, Bloom users got alerted to 47 analyst upgrades before the +market opened. + +[CTA Button: "Set Up Alerts"] +``` + +**Email 3: Day 4 (Social proof)** + +``` +Subject: What 52,000 investors found in Bloom +Preview: Real results from real users + +Body: +Bloom has a 4.8★ rating from 2,400+ reviews. Here's what investors say: + +"Found an insider buying pattern I never would've caught on my own." +"Replaced Seeking Alpha, Yahoo Finance, and 2 hours of morning research." +"The AI doesn't just summarize — it actually tells you what matters." + +The pattern: investors who research at least 3 stocks in their first +week are 4x more likely to keep using Bloom daily. + +You've researched [X] so far. Try 3 more today. + +[CTA Button: "Research a Stock"] +``` + +**Email 4: Day 7 (Value expansion)** + +``` +Subject: You're using 20% of Bloom +Preview: 3 features most users discover late + +Body: +You've been using Bloom for a week. Here are 3 things you probably +haven't tried yet: + +1. ASK THE AI A QUESTION +Type a question like "Is NVDA overvalued?" and get a sourced answer. +Not ChatGPT guessing — Bloom cites actual filings and data. + +2. COMPARE STOCKS +Search a stock and tap "Compare." Side-by-side analysis with AI +commentary on which metrics matter most. + +3. EARNINGS CALENDAR +See every upcoming earnings date for your watchlist. +Get the AI breakdown within minutes of the announcement. + +[CTA Button: "Try These Features"] +``` + +**Email 5: Day 10 (Upgrade push, if on free tier)** + +``` +Subject: Your free research limit resets tomorrow +Preview: Or unlock unlimited with Premium + +Body: +You've used [X] of your [Y] free AI research conversations this week. + +Here's what Premium unlocks: +✓ Unlimited AI research conversations +✓ Real-time insider trading alerts +✓ Advanced stock screeners +✓ Full analyst rating history + +50% off your first month: [LINK] + +Free users who upgrade within the first 2 weeks are the most active +investors on the platform. They research 3x more stocks. + +[CTA Button: "Get 50% Off Premium"] + +Not ready? No pressure. Your free tier resets tomorrow. Keep researching. +``` + +### Trial-to-Paid Conversion (3 emails during trial) + +**Email 1: Day 1 of trial** + +``` +Subject: Your Premium trial is live +Preview: Here's how to get the most out of the next 14 days + +Body: +You've got 14 days of Bloom Premium. Here's the fastest way to see +the difference: + +1. Search a stock you're considering buying +2. Read the full AI analysis (Premium shows 3x more depth) +3. Check the insider trading tab (Premium-only real-time data) +4. Set a smart alert for analyst rating changes + +Premium users research 3x more stocks and catch moves 2 days earlier +than free users on average. + +[CTA Button: "Start Researching"] +``` + +**Email 2: Day 10 (urgency + proof)** + +``` +Subject: 4 days left on your trial +Preview: Here's what you'll lose on [date] + +Body: +Your Premium trial ends in 4 days. + +Here's what goes away: +✗ Unlimited AI conversations (back to 5/day) +✗ Real-time insider trading data +✗ Advanced screeners +✗ Full analyst rating history + +During your trial, you've: +• Researched [X] stocks +• Received [Y] alerts +• [Personalized stat] + +Keep everything for $X/month. That's less than one Seeking Alpha +subscription. + +[CTA Button: "Keep Premium"] +``` + +**Email 3: Day 14 (last day)** + +``` +Subject: Your trial ends tonight +Preview: Lock in 50% off before midnight + +Body: +Premium expires at midnight. + +Last chance: 50% off your first 3 months. + +[CTA Button: "Lock In 50% Off"] + +After tonight: $X/month. Cancel anytime in one tap. +``` + +### Win-Back Sequence (users inactive 14+ days, 3 emails) + +**Email 1: Day 14 of inactivity** + +``` +Subject: NVDA got 3 analyst upgrades while you were away +Preview: Your watchlist had 7 alerts you missed + +Body: +While you were away, here's what happened to your watchlist: + +• NVDA: 3 analyst upgrades, price target raised to $180 +• AAPL: CEO bought $5M in stock +• TSLA: Beat earnings by 12% + +You missed these alerts because you haven't opened Bloom in 2 weeks. + +[CTA Button: "See What You Missed"] +``` + +Use real data from their watchlist. Generic "we miss you" emails get deleted. + +**Email 2: Day 21** + +``` +Subject: What changed in Bloom since you left +Preview: 2 new features you haven't seen + +Body: +We shipped 2 features since your last visit: + +1. [Newest feature with one-line benefit] +2. [Second newest feature with one-line benefit] + +Plus: your watchlist is still active and tracking [X] stocks. + +[CTA Button: "Open Bloom"] +``` + +**Email 3: Day 30 (final attempt)** + +``` +Subject: Should we keep your watchlist active? +Preview: We'll archive it in 7 days unless you log in + +Body: +You have [X] stocks on your watchlist with [Y] unread alerts. + +We'll keep tracking them for 7 more days. After that, we'll +pause alerts to save your battery and inbox. + +Want to keep them? Just open the app. + +[CTA Button: "Keep My Watchlist"] +``` + +### Email Anti-Patterns + +- ❌ "Dear Valued Customer" (use their name or nothing) +- ❌ Emails longer than 200 words (mobile readers, max 150 is better) +- ❌ Multiple CTAs in one email (one email, one action) +- ❌ HTML-heavy templates that look like ads (plain text converts better for lifecycle emails) +- ❌ Sending the same email to all users regardless of behavior +- ❌ "Unsubscribe to stop receiving these" buried in 6pt font (make it easy and honest) +- ❌ Subject lines that don't relate to body content (bait-and-switch kills trust) + +--- diff --git a/copywriting/references/7-ugc-script-templates.md b/copywriting/references/7-ugc-script-templates.md new file mode 100644 index 0000000..6e713d8 --- /dev/null +++ b/copywriting/references/7-ugc-script-templates.md @@ -0,0 +1,195 @@ +# 7. UGC Script Templates (AI-Generated Video) + +Script structures for AI-generated UGC testimonials. These pair with the Sora product integration pipeline (`sora/references/ugc-product-integration.md`) for full video production. + +## AI UGC Production Stack + +Before scripting, build the production infrastructure. See `whop-content-rewards` skill for full detail. Summary: + +**1. Find a reference ad first** +- Use [Meta Ad Library](https://facebook.com/ads/library) or [GetHooked.ai](https://gethooked.ai) — find ads in your category running 30+ days (run duration = proof of return) +- Watch 3x: map hook → product intro → proof → CTA structure explicitly. Use it as the script architecture, not a blank page. + +**2. Generate a credible avatar** +- Presenter = peer to target audience, not a spokesperson or actor +- For Bloom: working investor in their 30s, not a finance bro or formal advisor +- Tools: Midjourney, HeyGen. Generate 4–6 variants, pick the best demographic match. + +**3. Voice match precisely** +- Mismatch in age/energy/tone creates subconscious friction — viewers feel it without identifying it +- Tool: ElevenLabs (best micro-variation and pacing control) +- Test: place avatar image on screen, play voice samples — "can I genuinely imagine this person talking like this?" +- After generating: remove silences (Adobe Premiere silence removal) — trims 20–30s off a 3-min VO, improves pacing + +**4. Native caption formatting** +- 50–80% of Instagram viewers encounter content muted first — captions are not optional +- Use Instagram's native story text style (semi-transparent dark background) — brain registers it as organic, not ad +- Technique: generate inside Instagram app on throwaway photo → import into editor → remove background → overlay + +--- + +## Emotional Beat Structure + +Every UGC testimonial follows an emotional arc, not a flat pitch. Each beat has a specific energy level and purpose. + +``` +CURIOSITY (0-3s) — Moderate energy. Hook with intrigue, not hype. +PROBLEM (3-10s) — Energy dips. Frustration, relatability, empathy. +DISCOVERY (10-20s) — Energy builds. Hope, specific benefit, shift from frustration. +VALIDATION (20-28s) — Peak energy. Results, social proof, personal transformation. +CTA (28-35s) — Sustained but slightly softer. Clear next step, friendly not pushy. +``` + +The energy dip at PROBLEM is what makes DISCOVERY feel earned. Skip the dip and the whole thing sounds like an infomercial. + +## Template A: Pain Point Discovery (Excited Tone) + +**Actor direction:** Animated, talking fast, genuine surprise energy. + +``` +CURIOSITY (0-3s): +"Okay this is wild..." +[Text overlay: core claim or stat] + +PROBLEM (3-10s): +"I was literally spending [$ amount] on [competitor/old solution] +that barely worked. I tried [alternative 1], [alternative 2], +nothing actually fixed [specific pain]." + +DISCOVERY (10-20s): +"Then I found [product] and it completely changed everything. +Within [timeframe] I noticed [specific result]. +Like, [concrete detail only a real user would mention]." + +VALIDATION (20-28s): +"I'm seeing [specific outcome] I didn't think were possible. +Everyone around me has noticed. [Social proof detail]." + +CTA (28-35s): +"If you're dealing with [problem], seriously just try this. +You can thank me later." +[Text overlay: product name + where to get it] +``` + +## Template B: Social Proof Skeptic (Contemplative Tone) + +**Actor direction:** Calm, thoughtful, measured delivery. Credibility through restraint. + +``` +CURIOSITY (0-3s): +"So everyone's been talking about [product]..." + +PROBLEM (3-10s): +"And honestly I was skeptical because I've tried everything. +[Specific thing they tried]. [Another thing]. None of it stuck." + +DISCOVERY (10-20s): +"But after using it for [timeframe] I totally get the hype now. +The difference is [specific observable change]. +[Detail that shows actual usage, not marketing speak]." + +VALIDATION (20-28s): +"I'm actually recommending it to people, which I never do. +[Specific person or context where they recommended it]." + +CTA (28-35s): +"If you've been on the fence, this is the one." +[Text overlay: product name + CTA] +``` + +## Template C: Unboxing Reveal + +**Actor direction:** Excited anticipation → genuine reaction. Five segments, each gets its own video generation pass. + +``` +INTRO (0-10s): +"Okay so this just arrived and I'm actually so excited. +I've been hearing about [product] everywhere. +Everyone says it's completely different from [competitor]. +Let's see if it lives up to the hype." +[Talking head, selfie-style, package visible but unopened] + +UNBOXING (10-18s): +[POV overhead shot: hands opening package] +[First glimpse of product] +[Packaging details visible] +— No voiceover needed. Let the reveal breathe. + +FEATURES (18-30s): +[Actor holding product, examining it] +"Okay so right away I notice [physical quality detail]. +The [specific feature] is [observation]. +And look at [detail] — that's [comparison to competitor]." +[Multi-angle: front → side → detail closeup] + +DEMO (30-42s): +[Actor using the product in context] +[Show application/consumption/interaction] +"So [describing the experience in real time]. +[Genuine reaction to the experience]." + +VERDICT (42-50s): +"Honestly this exceeded my expectations. +If you've been considering [category], this is the one. +I'm already planning to [repeat purchase/recommend/etc]." +[Text overlay: product name + CTA] +``` + +**Production note:** Each segment is a separate video generation + composite pass. The unboxing POV (segment 2) uses a different camera angle than the talking head segments. + +## Template D: Lifestyle Context (Soft Sell) + +**Actor direction:** Natural, candid, product integrated into daily life rather than pitched. + +``` +CONTEXT (0-5s): +[Actor in natural environment: commuting, cooking, at desk, working out] +"So my [morning routine / commute / workout / evening] has been +completely different since I started using [product]." + +INTEGRATION (5-15s): +[Show product in use within the environment] +"I just [how they use it: take it, apply it, open it, check it] +and [immediate benefit]. It takes [time: seconds/minutes]." +[Product visible but not centered — lifestyle first, product second] + +CONTRAST (15-22s): +"Before I was [old behavior: slower, more complicated, worse results]. +Now I [new behavior]. [Specific metric or observable difference]." + +CLOSE (22-28s): +"Honestly it's one of those things where you wonder +why you didn't switch sooner." +[Text overlay: product name] +``` + +## Script Adaptation Rules + +**For different tones**, adjust these variables: +- **Excited:** Shorter sentences, interruptions ("like, wait"), faster pacing +- **Contemplative:** Longer pauses, qualifiers ("honestly," "actually"), measured delivery +- **Casual:** Filler words ("so," "like"), tangents that circle back, lower stakes language +- **Urgent:** Statistics, deadlines, scarcity cues, direct address ("you need to") + +**For different products**, adjust the PROBLEM beat: +- **Replacing a competitor:** Name the old solution's specific failure +- **New category:** Describe the gap ("I didn't even know this existed") +- **Upgrade:** Describe what they tolerated before ("I just accepted that...") +- **Impulse/lifestyle:** Skip PROBLEM, extend DISCOVERY with sensory details + +**For different durations:** +- **15 seconds:** CURIOSITY (2s) → DISCOVERY (8s) → CTA (5s). Skip PROBLEM and VALIDATION. +- **30 seconds:** Full structure, compressed. One sentence per beat. +- **45-60 seconds:** Full structure with room for details. Add second VALIDATION beat or DEMO segment. + +## Bloom-Specific Adaptations + +These templates work for Bloom ads by replacing generic placeholders: + +| Beat | Bloom-Specific Content | +|------|----------------------| +| PROBLEM | "Hours on Yahoo Finance, Reddit, Seeking Alpha. By the time I had a thesis, the stock already moved." | +| DISCOVERY | "Search any ticker. Full AI breakdown in 30 seconds: analyst ratings, insider trades, earnings, bull/bear case." | +| VALIDATION | "4.8 stars. 52,000 investors. The AI shows you WHERE it got the information." | +| CTA | "Free to download. Link in bio." | +| DEMO | Screen recording of Bloom: search NVDA → AI analysis → insider trades → earnings | diff --git a/copywriting/references/a-b-testing-framework.md b/copywriting/references/a-b-testing-framework.md new file mode 100644 index 0000000..706a240 --- /dev/null +++ b/copywriting/references/a-b-testing-framework.md @@ -0,0 +1,87 @@ +# A/B Testing Framework + +Test systematically. Most teams test randomly and learn nothing. + +### What to Test (In This Order) + +Testing priority ranked by conversion impact: + +| Priority | Element | Why | Min Sample | +|----------|---------|-----|-----------| +| 1 | **Headlines / Hooks** | Determines if anyone reads the rest | 500 per variant | +| 2 | **Hero image / Video thumbnail** | Determines if anyone clicks | 500 per variant | +| 3 | **CTA text and placement** | Determines if readers become users | 300 per variant | +| 4 | **Social proof** | Determines if uncertain visitors convert | 300 per variant | +| 5 | **Body copy** | Determines conversion rate for engaged readers | 1,000 per variant | +| 6 | **Pricing / Offer** | Determines revenue per conversion | 1,000 per variant | +| 7 | **Page layout** | Marginal gains after the above are optimized | 2,000 per variant | + +### Statistical Significance + +Don't call a winner too early. You need: + +- **Minimum sample**: 300-500 conversions per variant (not impressions, CONVERSIONS) +- **Confidence level**: 95% minimum (p < 0.05) +- **Test duration**: At least 7 days (captures weekly behavior cycles) +- **One variable at a time**: Changing headline AND image means you don't know which worked + +**Quick significance check**: If Variant B is beating Variant A by less than 10% relative lift, you probably need 2,000+ conversions per variant to confirm it's real. Big wins (30%+ lift) are detectable faster. + +### Testing by Channel + +#### Google Ads +- Use RSA headline/description rotation (Google's built-in testing) +- Create separate ad groups for major copy themes, not just keyword groups +- Test landing pages with Campaign Experiments (50/50 split) +- Run for 2+ weeks before judging (Google's learning period) + +#### App Store +- Use Apple's Product Page Optimization (3 treatments) +- Test screenshot order and text (highest impact) +- Test icon variants (second highest) +- Run for minimum 7 days, Apple recommends 14 +- Google Play: use Store Listing Experiments (up to 5 variants) + +#### TikTok / Meta +- Same video with 3 different hooks (first 2-3 seconds) +- Test CTA text: "Download Free" vs "Try It Free" vs "Get the App" +- Test thumbnail/first frame for feed placement +- Budget: min $50/day per variant for 5+ days + +#### Email +- Subject line A/B test on 20% of list, send winner to remaining 80% +- Test send time: 7 AM vs 10 AM vs 6 PM (user timezone) +- CTA button color is NOT worth testing until everything above is optimized +- Min list size per variant: 1,000 (for open rate), 5,000 (for click rate) + +#### Landing Pages +- Use UTM parameters to track which traffic source converts +- Test one element at a time (hero copy OR CTA text, not both) +- Run tests for full business cycles (7-14 days minimum) +- Tools: Google Optimize (free), VWO, Optimizely + +### Rapid Creative Testing (4-Day Blitz) + +For paid social (Meta/TikTok), the traditional test cycle is too slow: brief creators → wait for delivery → launch → wait for data → iterate = 4 weeks for 3 variations. This protocol gets 30 variations tested in 4 days: + +**Day 1: Generate 20 creative variations.** +Build a testing matrix: 3-5 different visual styles × 4-6 narrative angles × 2-3 emotional tones. Use Nano Banana Pro for visual cards, Larry for TikTok slideshows, screen recordings for demo variants. One operator, one day, 20 ads. + +**Day 2: Launch all 20 simultaneously.** +$20-50/day per variant. Broad targeting. Let the algorithm sort. Don't pre-judge which will win (you'll be wrong). + +**Day 3: Identify top 3-5 performers.** +Kill the bottom 75% based on CTR and conversion data. Don't wait for statistical significance on losers; you're looking for signal, not proof. + +**Day 4: Generate 10 iterations of winners.** +Take each winner's hook, angle, and format. Create variations: different opening lines, different proof points, different CTAs. Launch immediately. This is your second-generation creative set. + +**Why this works:** Traditional ugc costs $200-800 per video and 7-14 day turnaround. AI-generated creative (Nano Banana Pro for images, screen recordings for demos, Larry for slideshows) costs $2-8 per asset and takes minutes. The volume advantage means you find winners 10x faster. + +**Cadence:** Run a 4-day blitz at launch, then weekly 10-variation refreshes to fight creative fatigue. Every 60-90 days, run a full blitz with new angles. + +### The Testing Log + +Keep a testing log. Every test. + +```markdown diff --git a/copywriting/references/brand-voice-reference.md b/copywriting/references/brand-voice-reference.md new file mode 100644 index 0000000..b383766 --- /dev/null +++ b/copywriting/references/brand-voice-reference.md @@ -0,0 +1,27 @@ +# Brand Voice Reference + +**Read `~/marketing/WRITING-STYLE.md`** before writing any copy. Bloom's voice is concrete, specific, honest, and irreverent. Even in ads, we sound like a smart friend, not a corporation. "Start investing smarter" is generic. "See exactly why Tesla dropped 12% before your coworker does" is Bloom. + +## Voice and Tone Matrix + +Before writing, pin the brand on each axis. Bloom's defaults shown — adjust per context (e.g., error states skew more serious; TikTok skews more casual). + +| Axis | ← | → | Bloom default | +|------|---|---|---------------| +| Tone | Funny | Serious | 30% funny / 70% serious | +| Register | Casual | Formal | Casual | +| Edge | Irreverent | Respectful | Leans irreverent | +| Energy | Enthusiastic | Matter-of-fact | Matter-of-fact (facts > hype) | + +Use this to gut-check drafts: does the copy land where it should on each axis? If a line reads too corporate (formal + respectful + serious), it's off-brand. + +## Messaging Hierarchy + +Work top-down when building a campaign. Each level feeds the next. + +1. **Tagline** — one sentence, timeless, brand-level (e.g., "Invest like you mean it") +2. **Value proposition** — what the product does and for whom, one sentence +3. **Key messages** — 3 proof points that back the value prop +4. **Proof points** — specific data, stories, or stats that make each key message credible + +Don't skip to proof points. If the value prop is unclear, the proof points won't land. diff --git a/copywriting/references/copy-anti-patterns-kill-on-sight.md b/copywriting/references/copy-anti-patterns-kill-on-sight.md new file mode 100644 index 0000000..8215822 --- /dev/null +++ b/copywriting/references/copy-anti-patterns-kill-on-sight.md @@ -0,0 +1,66 @@ +# Copy Anti-Patterns (Kill on Sight) + +These patterns kill conversions. If you see them in any draft, rewrite immediately. + +### Feature Listing Without Benefits +``` +❌ "AI-powered analysis, real-time data, watchlists, alerts, screeners" +✅ "Research any stock in 30 seconds. AI reads the filings so you don't have to." +``` +Features are ingredients. Benefits are the meal. Nobody orders "flour, eggs, sugar." They order cake. + +### Being Clever Instead of Clear +``` +❌ "Where alpha meets artificial intelligence" +✅ "AI stock research. Search any stock, get the full picture." +``` +Clever copy makes the writer feel smart. Clear copy makes the reader take action. Every time you're tempted to be clever, ask: "Would my mom understand what this app does from this sentence?" + +### Burying the CTA +``` +❌ [500 words of features] ... [CTA at very bottom] +✅ [Headline] → [CTA] → [Supporting evidence] → [CTA again] +``` +Put the CTA within the first scroll. Then repeat it after every major section. Some people decide fast. Let them. + +### Weak CTAs +``` +❌ "Learn More" → learn more about WHAT? +❌ "Get Started" → started with WHAT? +❌ "Click Here" → nobody says "click here" in 2026 +❌ "Submit" → sounds like surrendering +❌ "Sign Up" → sounds like homework + +✅ "Download Bloom Free" → specific action + product + risk reversal +✅ "Start Investing Smarter" → benefit-driven +✅ "Research Your First Stock" → specific, immediate value +✅ "Get the App — It's Free" → action + risk reversal +``` + +### No Social Proof +If your landing page / ad / listing doesn't include at least ONE of these, it's incomplete: +- User count ("52,000 investors") +- Star rating ("4.8★ from 2,400+ reviews") +- Specific user result ("Found a 40% undervalued stock") +- Press mention ("Featured in TechCrunch") + +### Vague Value Props +``` +❌ "Powerful tools for smart investing" → what tools? how powerful? +❌ "Take control of your financial future" → means nothing specific +❌ "Invest with confidence" → cliché, no specifics +❌ "Your all-in-one investing solution" → every app says this + +✅ "AI reads 10-K filings so you don't have to" → specific, tangible +✅ "See analyst rating changes before the market opens" → specific timing +✅ "Search 6,000+ stocks. Get a breakdown in 30 seconds." → specific scope + speed +``` + +### The "We" Problem +``` +❌ "We built Bloom to help investors research smarter" +✅ "Research any stock in 30 seconds" +``` +The reader doesn't care about you. They care about what they get. Lead with "you" and the benefit, not "we" and the origin story. + +--- diff --git a/copywriting/references/copy-frameworks.md b/copywriting/references/copy-frameworks.md new file mode 100644 index 0000000..0abc812 --- /dev/null +++ b/copywriting/references/copy-frameworks.md @@ -0,0 +1,344 @@ +# Copy Frameworks Reference + +Headline formulas, page section types, and structural templates. + +## Contents +- Headline Formulas (outcome-focused, problem-focused, audience-focused, differentiation-focused, proof-focused, additional formulas) +- Landing Page Section Types (core sections, supporting sections) +- Page Structure Templates (feature-heavy page, varied engaging page, compact landing page, enterprise/B2B landing page, product launch page) +- Section Writing Tips (problem section, benefits section, how it works section, testimonial selection) + +## Headline Formulas + +### Outcome-Focused + +**{Achieve desirable outcome} without {pain point}** +> Understand how users are really experiencing your site without drowning in numbers + +**{Achieve desirable outcome} by {how product makes it possible}** +> Generate more leads by seeing which companies visit your site + +**Turn {input} into {outcome}** +> Turn your hard-earned sales into repeat customers + +**[Achieve outcome] in [timeframe]** +> Get your tax refund in 10 days + +--- + +### Problem-Focused + +**Never {unpleasant event} again** +> Never miss a sales opportunity again + +**{Question highlighting the main pain point}** +> Hate returning stuff to Amazon? + +**Stop [pain]. Start [pleasure].** +> Stop chasing invoices. Start getting paid on time. + +--- + +### Audience-Focused + +**{Key feature/product type} for {target audience}** +> Advanced analytics for Shopify e-commerce + +**{Key feature/product type} for {target audience} to {what it's used for}** +> An online whiteboard for teams to ideate and brainstorm together + +**You don't have to {skills or resources} to {achieve desirable outcome}** +> With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic + +--- + +### Differentiation-Focused + +**The {opposite of usual process} way to {achieve desirable outcome}** +> The easiest way to turn your passion into income + +**The [category] that [key differentiator]** +> The CRM that updates itself + +--- + +### Proof-Focused + +**[Number] [people] use [product] to [outcome]** +> 50,000 marketers use Drip to send better emails + +**{Key benefit of your product}** +> Sound clear in online meetings + +--- + +### Additional Formulas + +**The simple way to {outcome}** +> The simple way to track your time + +**Finally, {category} that {benefit}** +> Finally, accounting software that doesn't suck + +**{Outcome} without {common pain}** +> Build your website without writing code + +**Get {benefit} from your {thing}** +> Get more revenue from your existing traffic + +**{Action verb} your {thing} like {admirable example}** +> Market your SaaS like a Fortune 500 + +**What if you could {desirable outcome}?** +> What if you could close deals 30% faster? + +**Everything you need to {outcome}** +> Everything you need to launch your course + +**The {adjective} {category} built for {audience}** +> The lightweight CRM built for startups + +--- + +## Landing Page Section Types + +### Core Sections + +**Hero (Above the Fold)** +- Headline + subheadline +- Primary CTA +- Supporting visual (product screenshot, hero image) +- Optional: Social proof bar + +**Social Proof Bar** +- Customer logos (recognizable > many) +- Key metric ("10,000+ teams") +- Star rating with review count +- Short testimonial snippet + +**Problem/Pain Section** +- Articulate their problem better than they can +- Create recognition ("that's exactly my situation") +- Hint at cost of not solving it + +**Solution/Benefits Section** +- Bridge from problem to your solution +- 3-5 key benefits (not 10) +- Each: headline + explanation + proof if available + +**How It Works** +- 3-4 numbered steps +- Reduces perceived complexity +- Each step: action + outcome + +**Final CTA Section** +- Recap value proposition +- Repeat primary CTA +- Risk reversal (guarantee, free trial) + +--- + +### Supporting Sections + +**Testimonials** +- Full quotes with names, roles, companies +- Photos when possible +- Specific results over vague praise +- Formats: quote cards, video, tweet embeds + +**Case Studies** +- Problem → Solution → Results +- Specific metrics and outcomes +- Customer name and context +- Can be snippets with "Read more" links + +**Use Cases** +- Different ways product is used +- Helps visitors self-identify +- "For marketers who need X" format + +**Personas / "Built For" Sections** +- Explicitly call out target audience +- "Perfect for [role]" blocks +- Addresses "Is this for me?" question + +**FAQ Section** +- Address common objections +- Good for SEO +- Reduces support burden +- 5-10 most common questions + +**Comparison Section** +- vs. competitors (name them or don't) +- vs. status quo (spreadsheets, manual processes) +- Tables or side-by-side format + +**Integrations / Partners** +- Logos of tools you connect with +- "Works with your stack" messaging +- Builds credibility + +**Founder Story / Manifesto** +- Why you built this +- What you believe +- Emotional connection +- Differentiates from faceless competitors + +**Demo / Product Tour** +- Interactive demos +- Video walkthroughs +- GIF previews +- Shows product in action + +**Pricing Preview** +- Teaser even on non-pricing pages +- Starting price or "from $X/mo" +- Moves decision-makers forward + +**Guarantee / Risk Reversal** +- Money-back guarantee +- Free trial terms +- "Cancel anytime" +- Reduces friction + +**Stats Section** +- Key metrics that build credibility +- "10,000+ customers" +- "4.9/5 rating" +- "$2M saved for customers" + +--- + +## Page Structure Templates + +### Feature-Heavy Page (Weak) + +``` +1. Hero +2. Feature 1 +3. Feature 2 +4. Feature 3 +5. Feature 4 +6. CTA +``` + +This is a list, not a persuasive narrative. + +--- + +### Varied, Engaging Page (Strong) + +``` +1. Hero with clear value prop +2. Social proof bar (logos or stats) +3. Problem/pain section +4. How it works (3 steps) +5. Key benefits (2-3, not 10) +6. Testimonial +7. Use cases or personas +8. Comparison to alternatives +9. Case study snippet +10. FAQ +11. Final CTA with guarantee +``` + +This tells a story and addresses objections. + +--- + +### Compact Landing Page + +``` +1. Hero (headline, subhead, CTA, image) +2. Social proof bar +3. 3 key benefits with icons +4. Testimonial +5. How it works (3 steps) +6. Final CTA with guarantee +``` + +Good for ad landing pages where brevity matters. + +--- + +### Enterprise/B2B Landing Page + +``` +1. Hero (outcome-focused headline) +2. Logo bar (recognizable companies) +3. Problem section (business pain) +4. Solution overview +5. Use cases by role/department +6. Security/compliance section +7. Integration logos +8. Case study with metrics +9. ROI/value section +10. Contact/demo CTA +``` + +Addresses enterprise buyer concerns. + +--- + +### Product Launch Page + +``` +1. Hero with launch announcement +2. Video demo or walkthrough +3. Feature highlights (3-5) +4. Before/after comparison +5. Early testimonials +6. Launch pricing or early access offer +7. CTA with urgency +``` + +Good for ProductHunt, launches, or announcements. + +--- + +## Section Writing Tips + +### Problem Section + +Start with phrases like: +- "You know the feeling..." +- "If you're like most [role]..." +- "Every day, [audience] struggles with..." +- "We've all been there..." + +Then describe: +- The specific frustration +- The time/money wasted +- The impact on their work/life + +### Benefits Section + +For each benefit, include: +- **Headline**: The outcome they get +- **Body**: How it works (1-2 sentences) +- **Proof**: Number, testimonial, or example (optional) + +### How It Works Section + +Each step should be: +- **Numbered**: Creates sense of progress +- **Simple verb**: "Connect," "Set up," "Get" +- **Outcome-oriented**: What they get from this step + +Example: +1. Connect your tools (takes 2 minutes) +2. Set your preferences +3. Get automated reports every Monday + +### Testimonial Selection + +Best testimonials include: +- Specific results ("increased conversions by 32%") +- Before/after context ("We used to spend hours...") +- Role + company for credibility +- Something quotable and specific + +Avoid testimonials that just say: +- "Great product!" +- "Love it!" +- "Easy to use!" diff --git a/copywriting/references/direct-response-frameworks.md b/copywriting/references/direct-response-frameworks.md new file mode 100644 index 0000000..b4de7dd --- /dev/null +++ b/copywriting/references/direct-response-frameworks.md @@ -0,0 +1,568 @@ +# Copywriting Frameworks Reference + +This document contains 14 proven copywriting frameworks with selection guidance based on copy type, platform, and use case. + +--- + +## Framework Selection Matrix + +Use this matrix as a starting point — most frameworks work across multiple contexts. Choose based on your angle and audience awareness level. + +| Copy Type | Strong Options | Also Works Well | +|-----------|----------------|-----------------| +| Facebook/Instagram Ads | AIDA, PAS, BAB | FAB, 5-Point, G.R.A.B | +| TikTok/Reels/Shorts | G.R.A.B, PAS, SLAP | BAB, STAR Story | +| YouTube Pre-roll | AIDA, PAS | BAB, 5-Point | +| YouTube Long-form | PASTOR, AIDA | 5-Point, ACCA | +| Landing Pages | PAS, AIDA, BAB | PASTOR, 5-Point | +| Sales Pages (Long-form) | PASTOR, AIDA, 5-Point | PAS, BAB | +| Email Sequences | PAS, AIDA, QUEST | BAB, ACCA | +| LinkedIn Posts | BAB, AIDA, PAS | FAB, ACCA | +| E-commerce Product Ads | FAB, AIDA, PAS | BAB, 5-Point | +| Transformation/Coaching | BAB, PAS, PASTOR | AIDA, 4P | +| B2B/SaaS Ads | ACCA, PAS, AIDA | BAB, FAB | +| UGC/Influencer Scripts | STAR Story, PAS, G.R.A.B | BAB, AIDA | +| Retargeting Ads | QUEST, PAS, SLAP | AIDA, BAB | +| Advertorials | PASTOR, AIDA | 5-Point, PPPP | +| Product Launch | 5-Point, AIDA, PAS | BAB, FAB | +| Webinar/Event Promo | AIDA, PAS, BAB | 5-Point, QUEST | +| App Store Description | FAB, AIDA, PAS | BAB | +| Cold Outreach | PAS, BAB, AIDA | QUEST | +| Newsletter Promo | AIDA, PAS, 5-Point | BAB, QUEST | + +--- + +## Framework Details + +### 1. AIDA (Attention → Interest → Desire → Action) + +**The universal framework.** Works for almost any copy type. When in doubt, start here. + +**Works well for:** +- Social media ads (Facebook, Instagram, LinkedIn, Twitter/X) +- Landing pages and sales pages +- Email campaigns and newsletters +- YouTube ads and video scripts +- Product launches and announcements +- Webinar and event promotions +- Blog post intros and CTAs +- App store descriptions +- Print ads and billboards +- Pitch decks and presentations + +**Why it works:** Forces the classic funnel structure. Grabs attention, builds logical progression, creates desire, drives action. Flexible enough to adapt to any length or platform. + +**Use when:** You need a reliable structure that works anywhere. Great default when unsure which framework to use. + +**Structure:** +- **A - Attention:** Hook that stops the scroll. Bold claim, question, surprising stat, or pattern interrupt. +- **I - Interest:** Explain why this matters. Connect to their world. Build curiosity. +- **D - Desire:** Build emotional want. Show transformation, benefits, social proof. Make them feel the outcome. +- **A - Action:** Clear CTA. Tell them exactly what to do next. + +**Example (Facebook Ad):** +``` +[Attention] Tired of wasting money on ads that don't convert? +[Interest] Most businesses burn 60% of their ad budget on the wrong audience. +[Desire] Imagine knowing exactly who will buy before you spend a dollar. +[Action] Get our targeting framework free. Link in bio. +``` + +**Example (Landing Page Headline):** +``` +[Attention] Your competitors are stealing your customers while you sleep. +[Interest] 73% of buyers choose the first solution they find. +[Desire] Be that first solution with AI-powered SEO that ranks in 30 days. +[Action] Start your free trial → +``` + +**Example (Email Subject + Opening):** +``` +[Attention] Subject: The $50K mistake I made last quarter +[Interest] I thought more features = more sales. I was dead wrong. +[Desire] After cutting 40% of our product, revenue jumped 3x. +[Action] Here's the exact framework I used (steal it) → +``` + +--- + +### 2. PAS (Problem → Agitate → Solution) + +**The pain-driven powerhouse.** Fast, emotional, and direct. One of the most versatile frameworks. + +**Works well for:** +- Short-form social ads (Facebook, Instagram, TikTok, Twitter/X) +- UGC and influencer scripts +- Landing page headlines and hero sections +- Email subject lines and openers +- Cold outreach messages +- Product descriptions for problem-solving products +- LinkedIn posts +- Video ad scripts +- Sales page sections +- App notifications and push messages + +**Why it works:** Hits the emotional trigger hard and fast. Creates urgency through pain amplification. People are motivated more by avoiding pain than gaining pleasure. + +**Use when:** Your product solves a clear pain point. Works for SaaS, health, fitness, productivity, finance — anything where the "before" state hurts. + +**Structure:** +- **P - Problem:** State the pain clearly. Make them feel seen and understood. +- **A - Agitate:** Twist the knife. Show consequences of not solving it. Future-pace the pain. +- **S - Solution:** Present your product as the relief. Show the way out. + +**Example (Social Ad):** +``` +[Problem] Your calendar is chaos. Meetings eat your entire day. +[Agitate] Every hour wasted in pointless meetings is an hour you'll never get back. Your projects pile up. Your stress compounds. Your best ideas die in your inbox. +[Solution] TimeBlock AI automatically protects your focus time. No more death by calendar. +``` + +**Example (Cold Email):** +``` +[Problem] Hiring takes 3 months and burns $15K per role. +[Agitate] Meanwhile, your team is drowning, projects slip, and your best people start eyeing the door. +[Solution] Our pre-vetted talent pool fills roles in 2 weeks. Same quality, 70% less cost. +``` + +**Example (LinkedIn Post):** +``` +[Problem] Most founders work IN their business, not ON it. +[Agitate] You're the bottleneck. Every decision waits for you. Vacations feel impossible. Growth stalls at your capacity. +[Solution] Here's the delegation framework that freed up 20 hours of my week ↓ +``` + +--- + +### 3. BAB (Before → After → Bridge) + +**The transformation framework.** Perfect for showing the journey from pain to possibility. + +**Works well for:** +- Transformation-focused ads (fitness, coaching, courses) +- SaaS and productivity tools (show the workflow improvement) +- Case study formats +- LinkedIn posts and thought leadership +- Video testimonials structure +- Landing page hero sections +- Email sequences +- Sales conversations +- Before/after content +- Personal brand storytelling + +**Why it works:** Humans are wired for stories. BAB creates an instant mental movie of transformation. The "After" creates desire; the "Bridge" creates action. + +**Use when:** You want the viewer to instantly imagine the improved version of themselves or their business. + +**Structure:** +- **B - Before:** Paint their current painful reality. Make it specific and relatable. +- **A - After:** Show the transformed state they desire. Make it vivid and emotional. +- **B - Bridge:** Your product/solution is the path from before to after. + +**Example (Coaching/Course Ad):** +``` +[Before] 3 months ago, I was working 70-hour weeks and still behind on everything. +[After] Now I work 35 hours and my revenue doubled. +[Bridge] The difference? I replaced 12 tools with one system. Here's the exact setup. +``` + +**Example (SaaS Landing Page):** +``` +[Before] Before: Spreadsheets, sticky notes, and 47 browser tabs. Projects falling through cracks. +[After] After: One dashboard. Every task tracked. Nothing forgotten. Home by 6. +[Bridge] ProjectFlow is the system that makes it happen. Try it free. +``` + +**Example (LinkedIn Post):** +``` +[Before] 2 years ago I was mass-applying to jobs. 200 applications. 3 interviews. 0 offers. +[After] Last month I had 5 companies competing for me. Negotiated 40% above asking. +[Bridge] The difference? I stopped applying and started positioning. Here's how ↓ +``` + +--- + +### 4. FAB (Features → Advantages → Benefits) + +**The product-focused framework.** Translates specs into desire. + +**Works well for:** +- E-commerce product descriptions +- Tech and gadget ads +- SaaS feature announcements +- App store descriptions +- Product comparison pages +- Sales enablement materials +- Amazon listings +- Spec sheets that need to sell +- LinkedIn product posts +- Email product announcements + +**Why it works:** Quickly answers the three questions buyers ask: What is it? Why is it better? What do I get? Bridges the gap between features and emotional outcomes. + +**Use when:** Your product has clear features that drive tangible benefits. Great for tech, gadgets, software, and physical products. + +**Structure:** +- **F - Features:** What the product has or does (specs, capabilities, components). +- **A - Advantages:** Why that feature matters vs alternatives. The "so what?" +- **B - Benefits:** What the customer actually gets (emotional/practical outcome). + +**Example (E-commerce):** +``` +[Feature] 48-hour battery life. +[Advantage] Most headphones die in 8 hours. These last your entire work week. +[Benefit] Never interrupt your flow to charge. Just grab and go. +``` + +**Example (SaaS Feature):** +``` +[Feature] AI-powered inbox sorting. +[Advantage] Unlike filters that miss context, it learns what matters to YOU. +[Benefit] Start your day with the 5 emails that actually need attention. Ignore the rest. +``` + +**Example (App Store):** +``` +[Feature] Offline mode with full sync. +[Advantage] Competitors require constant internet. We don't. +[Benefit] Work from planes, subways, or that cabin with zero bars. Pick up exactly where you left off. +``` + +--- + +### 5. 4Cs (Clear → Concise → Compelling → Credible) + +**The editing framework.** Not a writing structure — a quality filter. + +**Use for:** Refining ANY copy written with another framework. Apply as a final polish. + +**Checklist:** +- **Clear:** Is the message instantly understandable? No jargon or ambiguity? +- **Concise:** Can any word be cut without losing meaning? Is every sentence earning its place? +- **Compelling:** Does it create desire or urgency? Would YOU click/buy/act? +- **Credible:** Is there proof? Stats? Social proof? Does it feel real? + +**Pro tip:** Read your copy aloud. If you stumble, it's not clear. If you're bored, it's not compelling. + +--- + +### 6. 5-Point Copy Formula (Promise → Picture → Proof → Push → Prompt) + +**The persuasion complete package.** Covers all bases: emotion, visualization, credibility, urgency. + +**Works well for:** +- Product launches and announcements +- Sales pages (short to medium length) +- Crowdfunding campaigns +- Course and program sales +- High-ticket offers +- Webinar pitches +- Facebook/Instagram ads with social proof +- Email sales sequences +- Landing pages with strong testimonials + +**Why it works:** Creates vivid desire AND backs it up with proof in one flow. Doesn't rely on just emotion or just logic — uses both. + +**Use when:** You have strong testimonials, case studies, or data to lean on. Great for offers where credibility drives conversion. + +**Structure:** +- **Promise:** Make a bold, specific claim about the outcome. +- **Picture:** Help them visualize having that outcome. Paint the scene. +- **Proof:** Back it up with testimonials, stats, case studies. +- **Push:** Create urgency. Why act now? +- **Prompt:** Clear, specific CTA. + +**Example (Course Sales):** +``` +[Promise] Double your email open rates in 14 days. +[Picture] Imagine waking up to replies from dream clients instead of crickets. Your inbox becomes a revenue stream, not a time sink. +[Proof] 2,400+ marketers have used this system. Average improvement: 127%. "Went from 12% to 41% opens in week one." — Sarah K. +[Push] We're closing enrollment Friday. Only 50 spots left at this price. +[Prompt] Grab your spot now → +``` + +--- + +### 7. PASTOR (Problem → Amplify → Story → Transformation → Offer → Response) + +**The long-form storyteller.** For when you need to build deep emotional connection. + +**Works well for:** +- Long-form sales pages +- Advertorials and native ads +- VSLs (video sales letters) +- Email sequences (spread across multiple emails) +- Complex products requiring education +- High-ticket coaching and consulting offers +- Webinar scripts +- Case study deep-dives + +**Why it works:** Story-driven and methodical. Builds emotional investment before asking for the sale. Perfect for higher-priced or complex offers. + +**Use when:** Your product needs narrative appeal, the buyer journey is longer, or you're selling something that requires trust. + +**Structure:** +- **P - Problem:** Identify and describe the pain in detail. +- **A - Amplify:** Make the problem feel urgent and serious. Stakes and consequences. +- **S - Story:** Tell a relatable story (yours or a customer's). +- **T - Transformation:** Show the before/after change vividly. +- **O - Offer:** Present your solution and everything they get. +- **R - Response:** Call to action with urgency or scarcity. + +--- + +### 8. ACCA (Awareness → Comprehension → Conviction → Action) + +**The educator's framework.** Teach first, sell second. + +**Works well for:** +- B2B and enterprise sales +- Complex SaaS products +- Financial services and insurance +- Technical products +- New category creation +- LinkedIn thought leadership +- Webinar funnels +- Email nurture sequences +- White paper lead-ins + +**Why it works:** Some products need explanation before desire. ACCA builds understanding first, then converts that understanding into conviction. + +**Use when:** The viewer needs context to appreciate your value. Great for innovative or technical products. + +**Structure:** +- **A - Awareness:** Make them aware of the problem or opportunity they didn't know existed. +- **C - Comprehension:** Help them understand the solution and how it works. +- **C - Conviction:** Build belief through proof, benefits, and trust signals. +- **A - Action:** Clear CTA. + +**Example (B2B SaaS):** +``` +[Awareness] 73% of B2B deals stall because buyers can't explain your product internally. +[Comprehension] Our platform auto-generates internal pitch decks your champions can share. One click, personalized for their stakeholders. +[Conviction] Used by Stripe, Notion, and 200+ B2B companies. Avg deal cycle reduced by 40%. +[Action] See how it works in 2 minutes → +``` + +--- + +### 9. QUEST (Qualify → Understand → Educate → Stimulate → Transition) + +**The nurturing framework.** For warm audiences who need a gentle push. + +**Works well for:** +- Retargeting campaigns +- Email nurture sequences +- Newsletter content +- LinkedIn posts (educational angle) +- Middle-of-funnel content +- Webinar follow-ups +- Community engagement + +**Why it works:** Qualifies + educates in a smooth sequence. Builds relationship before selling. Feels helpful, not pushy. + +**Use when:** You already have some user awareness or you're retargeting. Also great for filtering to ideal customers. + +**Structure:** +- **Q - Qualify:** Filter for your ideal audience. "This is for you if..." +- **U - Understand:** Show you understand their specific situation. +- **E - Educate:** Share valuable insight or information. +- **S - Stimulate:** Create desire for more or for the solution. +- **T - Transition:** Move them to the next step naturally. + +--- + +### 10. 4P (Picture → Promise → Prove → Push) + +**The fast converter.** Story + proof + action in tight package. + +**Works well for:** +- Conversion-heavy ads +- Retargeting +- Sales page sections +- Email CTAs +- Bold claims that need backing + +**Why it works:** Mixes emotion + logic + proof efficiently. Fast path from visualization to action. + +**Use when:** You want a quick path from story to CTA, but still need credibility. + +**Structure:** +- **Picture:** Paint a vivid scene of their desired outcome or current pain. +- **Promise:** Make a specific promise about what you'll deliver. +- **Prove:** Back it up with evidence. +- **Push:** Create urgency and CTA. + +--- + +### 11. PPPP (Picture → Promise → Prove → Push) + +**The dramatic storyteller.** Classic long-form format with big promises. + +**Works well for:** +- Long sales letters +- Traditional display ads +- Story-first campaigns +- Infomercial scripts +- Direct response campaigns + +**Why it works:** Proven "catalog copy" format. Creates emotional movie, makes bold promise, proves it, drives action. + +**Use when:** You want dramatic, story-first copy with big promises and have proof to back them. + +--- + +### 12. STAR Story Solution (Situation → Task → Action → Result → Solution) + +**The narrative framework.** Hero's journey in 60 seconds. + +**Works well for:** +- UGC and influencer content +- Video ads (TikTok, Reels, YouTube) +- Podcast ads +- Case study format +- Testimonial structures +- LinkedIn posts +- Founder story content + +**Why it works:** Gives you a "hero + problem + fix" structure that's perfect for authentic storytelling. Feels real, not salesy. + +**Use when:** The narrative is your strongest selling element. Great for UGC, testimonials, and personal brand content. + +**Structure:** +- **S - Situation:** Set the scene. Where were you/they? What was life like? +- **T - Task:** What needed to be done? What was the challenge? +- **A - Action:** What did you/they do? What was tried? +- **R - Result:** What happened? The outcome. +- **Solution:** Connect it to your product naturally. + +**Example (UGC Script):** +``` +[Situation] Last year I was working 80 hours a week and still drowning. +[Task] I needed to 10x my output without hiring a team. +[Action] I tested 47 different AI tools over 3 months. +[Result] Found one that literally cut my work in half. +[Solution] Now I use it daily. Here's my exact workflow. +``` + +--- + +### 13. G.R.A.B (Get Attention → Relate → Action → Benefit) + +**The thumb-stopper.** Built for the first 3 seconds. + +**Works well for:** +- TikTok and Reels +- YouTube Shorts +- Instagram Stories +- Any short-form video +- Feed ads +- Push notifications + +**Why it works:** Very fast emotional arc. Optimized for short attention spans and scroll culture. + +**Use when:** You have under 10 seconds to hook and convert. Speed is everything. + +**Structure:** +- **G - Get Attention:** Pattern interrupt. Bold statement. Visual hook. +- **R - Relate:** Quick connection to their reality. "If you're like me..." +- **A - Action:** What to do. +- **B - Benefit:** What they get. + +**Example:** +``` +[Get Attention] Stop scrolling. This saved my business. +[Relate] If you're tired of posting content that gets ignored... +[Action] Try this one hook format. +[Benefit] I went from 200 to 20,000 views in a week. +``` + +--- + +### 14. SLAP (Stop → Look → Act → Purchase) + +**The simplicity framework.** For high-volume, fast-twitch ads. + +**Works well for:** +- Feed ads at scale +- Retargeting +- Flash sales +- Limited time offers +- App install campaigns +- E-commerce promotions + +**Why it works:** Simple and fast. No complexity. Stop them, hook them, convert them. + +**Use when:** You're running high-volume ads that need speed and simplicity. Great for offers that don't need explanation. + +**Structure:** +- **S - Stop:** Pattern interrupt. Something unexpected. +- **L - Look:** Give them a reason to keep watching/reading. +- **A - Act:** Tell them what to do. +- **P - Purchase:** Make the buy easy and clear. + +--- + +## Quick Reference: Framework by Goal + +| Goal | Top Choices | Also Consider | +|------|-------------|---------------| +| Quick conversion | PAS, SLAP, G.R.A.B | AIDA, 4P | +| Build trust first | ACCA, QUEST, PASTOR | AIDA, 5-Point | +| Show transformation | BAB, STAR Story, 4P | PAS, AIDA | +| Highlight features | FAB, AIDA | PAS, 5-Point | +| Long-form selling | PASTOR, 5-Point, AIDA | PPPP, ACCA | +| Retargeting | QUEST, PAS, SLAP | AIDA, BAB | +| Education-heavy | ACCA, PASTOR, QUEST | AIDA, FAB | +| UGC/Influencer | STAR Story, PAS, G.R.A.B | BAB, AIDA | +| Storytelling | PASTOR, BAB, STAR Story | AIDA, PPPP | +| Product launch | AIDA, 5-Point, PAS | BAB, FAB | + +--- + +## Quick Reference: Framework by Platform + +| Platform | Top Choices | Also Consider | +|----------|-------------|---------------| +| Facebook Ads | AIDA, PAS, BAB | 5-Point, FAB | +| Instagram Ads | PAS, BAB, AIDA | G.R.A.B, FAB | +| TikTok | G.R.A.B, PAS, SLAP | BAB, STAR Story | +| YouTube (short) | AIDA, PAS, G.R.A.B | BAB | +| YouTube (long) | PASTOR, AIDA, 5-Point | ACCA | +| LinkedIn | AIDA, BAB, PAS | ACCA, FAB | +| Twitter/X | PAS, AIDA, G.R.A.B | BAB | +| Email | PAS, AIDA, QUEST | BAB, 5-Point | +| Landing Page | AIDA, PAS, BAB | PASTOR, 5-Point | +| Sales Page | PASTOR, AIDA, 5-Point | PAS, BAB | +| E-commerce | FAB, AIDA, PAS | BAB, 5-Point | + +--- + +## Choosing Between Frameworks + +**When multiple frameworks could work, consider:** + +1. **Audience awareness level** + - Unaware of problem → ACCA, AIDA + - Problem-aware → PAS, BAB + - Solution-aware → FAB, 5-Point + - Product-aware → SLAP, QUEST + +2. **Copy length available** + - < 50 words → G.R.A.B, SLAP, PAS + - 50-200 words → AIDA, PAS, BAB, FAB + - 200-500 words → AIDA, 5-Point, ACCA + - 500+ words → PASTOR, AIDA, PPPP + +3. **Primary angle** + - Pain-focused → PAS + - Transformation-focused → BAB + - Feature-focused → FAB + - Story-focused → PASTOR, STAR Story + - Proof-focused → 5-Point + +4. **Default choice when unsure: AIDA or PAS** + - AIDA if you need structure and flexibility + - PAS if the pain point is strong and clear + +--- diff --git a/copywriting/references/direct-response-principles.md b/copywriting/references/direct-response-principles.md new file mode 100644 index 0000000..6edc74a --- /dev/null +++ b/copywriting/references/direct-response-principles.md @@ -0,0 +1,116 @@ +# Direct Response Principles + +These are not suggestions. They're the physics of conversion copy. + +### Emotion First, Logic Second + +People buy on emotion and justify with logic. This has been true for 2,000 years (Cicero used it to win elections in 63 BC). Every piece of copy that moves people works on this principle — fear, hope, pride, frustration, relief. The product is never the subject. The emotion is. The product is the exit. + +Apply the sequence: make them feel something → then give them the rational justification to act. + +### Open Loops + +An open loop is an unresolved question in the reader's mind. The brain has physical discomfort with unresolved information (Zeigarnik Effect: incomplete tasks are remembered far better than completed ones). Open a loop early and delay closing it as long as possible. + +- "I spent $5k on XYZ and I hate what I found…" — reader can't stop until they know what was found +- "Here's what nobody tells you about picking stocks" — reader needs to see it before leaving +- Tease a result, reveal, or test in the hook — hold the payoff until the end + +**Rule:** Open a loop in the first line. Close it only in the CTA or final beat. + +### Curiosity Gap + +The space between what someone knows and what they want to know. Foreshadow the destination, withhold the route. + +- Movie shows the ending first, cuts to "72 hours earlier" — you watch for 2 hours because you know where it ends but not how +- In copy: state the outcome early ("how I 10x'd my research speed"), then build toward it — never give the answer before the middle + +Curiosity gap sustains attention between the open loop (tension) and the close (payoff). + +--- + +### AIDA (Attention → Interest → Desire → Action) + +Every piece of copy follows this arc. The mistake is spending 80% on Attention and 5% on Action. + +| Stage | Job | Example (Bloom) | +|-------|-----|-----------------| +| **Attention** | Stop the scroll. Pattern interrupt. | "Your portfolio dropped 4% today. Do you know why?" | +| **Interest** | Connect to their problem. Be specific. | "Most investors find out what moved their stocks 3 days late. From a CNBC headline." | +| **Desire** | Show the outcome. Make it tangible. | "Bloom gives you the exact catalyst, analyst rating changes, and insider trades. In real time." | +| **Action** | Tell them exactly what to do. One action. | "Download free. See your first stock breakdown in 60 seconds." | + +### PAS (Problem → Agitate → Solve) + +More aggressive than AIDA. Best for audiences that know they have a problem but haven't solved it yet. + +- **Problem**: Name it. Specifically. "You're checking 4 apps and 6 tabs to research one stock." +- **Agitate**: Make the pain vivid. "By the time you piece it all together, the move already happened. You're always a day late." +- **Solve**: Position your product as the obvious fix. "Bloom pulls everything into one screen. Analyst ratings, insider trades, earnings, catalysts. Research a stock in 30 seconds, not 30 minutes." + +### The Offer Stack + +What you get + bonuses + guarantee + urgency = irresistible offer. + +``` +WHAT YOU GET: +✓ AI-powered stock research (covers 6,000+ tickers) +✓ Real-time analyst rating changes +✓ Insider trading alerts +✓ Earnings breakdowns before and after + +BONUS: +✓ Watchlist with smart alerts (free tier) +✓ AI chat that actually cites sources + +GUARANTEE: +✓ Free to download. No credit card. Cancel anytime. + +URGENCY: +✓ "Premium is 50% off for the first 1,000 users this month" +``` + +Even for a free app download, stack the value. List everything they get. Make free feel like a steal. + +### Risk Reversal + +Remove every reason NOT to act. +- "Free to download" → removes cost objection +- "No credit card required" → removes commitment fear +- "Cancel anytime" → removes lock-in anxiety +- "Takes 30 seconds to set up" → removes time objection +- "Used by 50,000+ investors" → removes "is this legit?" doubt + +### Urgency and Scarcity + +Only use when real. Fake urgency destroys trust. + +- ✅ "Premium is 50% off through January" (real deadline) +- ✅ "Limited to first 1,000 users" (real cap) +- ✅ "Earnings season starts Monday. Set up alerts now." (real event) +- ❌ "Limited time offer!" (meaningless) +- ❌ "Don't miss out!" (says nothing) +- ❌ Countdown timers that reset on page refresh (fraud) + +### Specificity Sells + +The specific is more believable than the general. Always. + +| ❌ Generic | ✅ Specific | +|-----------|------------| +| "Powerful stock research" | "Research any stock in 30 seconds" | +| "AI-powered insights" | "AI that reads 10-K filings so you don't have to" | +| "Stay informed" | "Get alerts when analysts upgrade your stocks" | +| "Trusted by thousands" | "Used by 52,000 investors" | +| "Save time" | "Replace 6 tabs with 1 screen" | + +### Social Proof + +Types ranked by conversion impact: +1. **Specific numbers**: "52,000 investors use Bloom" > "thousands of users" +2. **Star ratings**: "4.8★ on the App Store (2,400+ ratings)" +3. **User quotes with specifics**: "I found a 40% undervalued stock in my first week" > "Great app!" +4. **Authority**: "Featured in TechCrunch, Product Hunt #1" +5. **Velocity**: "1,000 new users last week" (momentum > total) + +--- diff --git a/copywriting/references/lead-magnet-patterns.md b/copywriting/references/lead-magnet-patterns.md new file mode 100644 index 0000000..abfa502 --- /dev/null +++ b/copywriting/references/lead-magnet-patterns.md @@ -0,0 +1,276 @@ +# Lead Magnet Post Patterns + +This reference contains proven patterns for lead magnet giveaway posts that maximize comments and DM opt-ins. + +> **Note:** Opening hooks are generated using `viral-hook-creator` patterns. This file focuses on value anchors, CTAs, and post structure. + +--- + +## The Psychology + +Lead magnet posts work because they stack three psychological triggers: +1. **Viral hook** — Stops the scroll with curiosity (from viral-hook-creator) +2. **Value perception** — "This is worth real money" +3. **Low friction** — "All I have to do is comment" + +Miss any of these and engagement drops significantly. + +--- + +## Value Anchor Patterns + +Value anchors make the free offer feel valuable. Without them, people assume it's low quality. + +### Direct Price Anchors +- "Could easily charge $[X] for this." +- "This would cost $[X] from a consultant." +- "Worth at least $[X] based on what's inside." +- "Normally $[X]." + +### Scarcity/Urgency Anchors +- "Will charge $[X] for it in [Y] days." +- "Free for the next 48 hours." +- "Going behind a paywall next week." +- "First [X] people only." + +### Social Proof Anchors +- "[X] people have already grabbed this." +- "[X]+ downloads in the first week." +- "The same framework [notable person/company] uses." + +### Implicit Value Anchors +- "What I wish I had when I started..." +- "This took me [X] years to figure out..." +- "The exact [thing] I used to [achieve result]..." + +--- + +## CTA Patterns + +The CTA must be crystal clear and low friction. + +### Twitter/X CTAs +**Standard:** +``` +Comment "[WORD]" and I'll send it to you for free (must be following) +``` + +**With Like:** +``` +Like + Comment "[WORD]" and it's yours for free. + +(Must be following so I can DM you) +``` + +**With Repost:** +``` +Comment "[WORD]" and I'll DM you. + +Repost to help others find this. + +(Must be following) +``` + +### LinkedIn CTAs +**Standard:** +``` +1. Connect with me +2. Comment "[WORD]" + +I'll send it straight to your DMs. + +P.S. Repost for priority in the queue +``` + +**Alternative:** +``` +Want it? Here's how: + +1. Connect with me (so I can message you) +2. Comment "[WORD]" below + +I'll DM you the link. + +P.S. Repost this and I'll prioritize your DM +``` + +--- + +## Trigger Word Selection + +The trigger word should be: +- **Relevant** to the lead magnet (FRAMEWORK, CHECKLIST, TEMPLATE, GUIDE, etc.) +- **Memorable** and easy to type +- **Uppercase** for visibility + +### Common Trigger Words by Lead Magnet Type +- Framework → "FRAMEWORK" +- Checklist → "CHECKLIST" or "LIST" +- Template → "TEMPLATE" +- Course → "COURSE" or "FREE" +- Guide → "GUIDE" +- Playbook → "PLAYBOOK" +- Swipe file → "SWIPE" +- Tool/Software → "TOOL" or product name +- Blueprint → "BLUEPRINT" +- Custom/Specific → Use the product name (e.g., "SKILL") + +--- + +## Post Structures + +### Quick Format Structure +``` +[OPENING HOOK - from viral-hook-creator] + +[WHAT YOU BUILT] + +[VALUE ANCHOR] + +[CTA] +``` + +**Example:** +``` +I spent 3 months studying every #1 Product Hunt launch. + +Then I built a Claude Skill that gives you a personalized launch checklist based on YOUR product. + +Could easily charge $99 for this. + +Comment "SKILL" and I'll send it to you for free (must be following) +``` + +### Detailed Format Structure +``` +[OPENING HOOK - from viral-hook-creator] + +[WHAT YOU BUILT] + +Inside you'll find: + +→ [Benefit/content 1] +→ [Benefit/content 2] +→ [Benefit/content 3] +→ [Benefit/content 4] + +Want the full [playbook/framework/guide]? + +[CTA] +``` + +**Example:** +``` +I spent over 100+ hours researching the best prompts for Claude, Gemini and OpenAI. + +So I built a blueprint on how to prompt AI the right way. + +Inside you'll find: + +→ 100+ examples on how to actually prompt AI the right way +→ A guidebook on the best AI tools for specific tasks +→ Why traditional prompting won't cut it anymore +→ How to use the tools in sync + +Want the full playbook? + +Comment "FRAMEWORK" and I'll send it to you. + +(Must be following) +``` + +--- + +## High-Performing Examples + +### Example 1: SaaS Framework (Quick Format) +``` +My team & I have developed dozens of SaaS products that raised over 150M+ combined. + +So I've spent 73 hours packaging our learnings into this Framework. + +Will charge $199 for it in 7 days. + +Like + Comment "framework" and it's yours for free. + +(Must be following so I can DM you) +``` + +**Why it works:** +- Team credibility + specific achievement ($150M) +- Specific time investment (73 hours) +- Urgency anchor (7 days) +- Like + Comment increases engagement + +### Example 2: AI Prompting Guide (Detailed Format) +``` +I spent over 100+ hours researching the best prompts for Claude, Gemini and OpenAI. + +So I built a blueprint on how to prompt AI the right way. + +Inside you'll find: + +→ 100+ examples on how to actually prompt AI the right way +→ A guidebook on the best AI tools for specific tasks +→ Why traditional prompting won't cut it anymore +→ How to use the tools in sync + +Want the full playbook? + +Comment "FRAMEWORK" and I'll send it to you. + +(Must be following) +``` + +**Why it works:** +- Specific time investment (100+ hours) +- Clear deliverable (blueprint) +- 4 specific bullet points showing value +- Simple CTA + +### Example 3: Product Hunt Skill (Quick Format) +``` +I spent 3 months studying every #1 Product Hunt launch. + +Then I built a Claude Skill that gives you a personalized launch checklist based on YOUR product. + +Could easily charge $99 for this. + +Comment "SKILL" and I'll send it to you for free (must be following) +``` + +**Why it works:** +- Time investment with specific scope (every #1 launch) +- Personalization angle (based on YOUR product) +- Reasonable price anchor ($99) +- Direct CTA + +--- + +## Common Mistakes to Avoid + +1. **Weak opening hook** — Generic opener vs viral hook pattern with trigger words +2. **No value anchor** — Without price context, free feels worthless +3. **Vague bullets** — "Useful tips" vs "47 email subject lines that got 60%+ open rates" +4. **Complex CTA** — More than 2 steps kills conversion +5. **Wrong trigger word** — Generic words like "YES" or "ME" get lost in comments +6. **Missing "must be following"** — You can't DM non-followers on most platforms +7. **Too salesy** — Lead magnet posts should feel generous, not pushy + +--- + +## Platform-Specific Notes + +### Twitter/X +- Long-form posts work well +- "Must be following" is essential for DMs +- Repost requests can double reach +- Thread format can work for very detailed lead magnets + +### LinkedIn +- "Connect with me" is necessary (can't message non-connections) +- More professional tone, but still direct +- "Repost for priority" creates urgency +- Avoid hashtags in the main post body + +--- diff --git a/copywriting/references/natural-transitions.md b/copywriting/references/natural-transitions.md new file mode 100644 index 0000000..ee72faa --- /dev/null +++ b/copywriting/references/natural-transitions.md @@ -0,0 +1,272 @@ +# Natural Transitions + +Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure. + +Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices + +--- + +## Contents +- Previewing Content Structure +- Introducing a New Topic +- Referring Back +- Moving Between Sections +- Indicating Addition +- Indicating Contrast +- Indicating Similarity +- Indicating Cause and Effect +- Giving Examples +- Emphasising Key Points +- Providing Evidence (neutral attribution, expert quotes, supporting claims) +- Summarising Sections +- Concluding Content +- Question-Based Transitions +- List Introductions +- Hedging Language +- Best Practice Guidelines +- Transitions to Avoid (AI Tells) + +## Previewing Content Structure + +Use to orient readers and set expectations: + +- Here's what we'll cover... +- This guide walks you through... +- Below, you'll find... +- We'll start with X, then move to Y... +- First, let's look at... +- Let's break this down step by step. +- The sections below explain... + +--- + +## Introducing a New Topic + +- When it comes to X,... +- Regarding X,... +- Speaking of X,... +- Now let's talk about X. +- Another key factor is... +- X is worth exploring because... + +--- + +## Referring Back + +Use to connect ideas and reinforce key points: + +- As mentioned earlier,... +- As we covered above,... +- Remember when we discussed X? +- Building on that point,... +- Going back to X,... +- Earlier, we explained that... + +--- + +## Moving Between Sections + +- Now let's look at... +- Next up:... +- Moving on to... +- With that covered, let's turn to... +- Now that you understand X, here's Y. +- That brings us to... + +--- + +## Indicating Addition + +- Also,... +- Plus,... +- On top of that,... +- What's more,... +- Another benefit is... +- Beyond that,... +- In addition,... +- There's also... + +**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused. + +--- + +## Indicating Contrast + +- However,... +- But,... +- That said,... +- On the flip side,... +- In contrast,... +- Unlike X, Y... +- While X is true, Y... +- Despite this,... + +--- + +## Indicating Similarity + +- Similarly,... +- Likewise,... +- In the same way,... +- Just like X, Y also... +- This mirrors... +- The same applies to... + +--- + +## Indicating Cause and Effect + +- So,... +- This means... +- As a result,... +- That's why... +- Because of this,... +- This leads to... +- The outcome?... +- Here's what happens:... + +--- + +## Giving Examples + +- For example,... +- For instance,... +- Here's an example:... +- Take X, for instance. +- Consider this:... +- A good example is... +- To illustrate,... +- Like when... +- Say you want to... + +--- + +## Emphasising Key Points + +- Here's the key takeaway:... +- The important thing is... +- What matters most is... +- Don't miss this:... +- Pay attention to... +- This is critical:... +- The bottom line?... + +--- + +## Providing Evidence + +Use when citing sources, data, or expert opinions: + +### Neutral attribution +- According to [Source],... +- [Source] reports that... +- Research shows that... +- Data from [Source] indicates... +- A study by [Source] found... + +### Expert quotes +- As [Expert] puts it,... +- [Expert] explains,... +- In the words of [Expert],... +- [Expert] notes that... + +### Supporting claims +- This is backed by... +- Evidence suggests... +- The numbers confirm... +- This aligns with findings from... + +--- + +## Summarising Sections + +- To recap,... +- Here's the short version:... +- In short,... +- The takeaway?... +- So what does this mean?... +- Let's pull this together:... +- Quick summary:... + +--- + +## Concluding Content + +- Wrapping up,... +- The bottom line is... +- Here's what to do next:... +- To sum up,... +- Final thoughts:... +- Ready to get started?... +- Now it's your turn. + +**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing. + +--- + +## Question-Based Transitions + +Useful for conversational tone and featured snippet optimization: + +- So what does this mean for you? +- But why does this matter? +- How do you actually do this? +- What's the catch? +- Sound complicated? It's not. +- Wondering where to start? +- Still not sure? Here's the breakdown. + +--- + +## List Introductions + +For numbered lists and step-by-step content: + +- Here's how to do it: +- Follow these steps: +- The process is straightforward: +- Here's what you need to know: +- Key things to consider: +- The main factors are: + +--- + +## Hedging Language + +For claims that need qualification or aren't absolute: + +- may, might, could +- tends to, generally +- often, usually, typically +- in most cases +- it appears that +- evidence suggests +- this can help +- many experts believe + +--- + +## Best Practice Guidelines + +1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions +2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way) +3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition +4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate +5. **Keep it natural**: Read aloud; if it sounds forced, simplify +6. **Front-load key info**: Put the important word or phrase early in the transition + +--- + +## Transitions to Avoid (AI Tells) + +These phrases are overused in AI-generated content: + +- "That being said,..." +- "It's worth noting that..." +- "At its core,..." +- "In today's digital landscape,..." +- "When it comes to the realm of..." +- "This begs the question..." +- "Let's delve into..." + +See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells. diff --git a/copywriting/references/platform-character-limits-reference.md b/copywriting/references/platform-character-limits-reference.md new file mode 100644 index 0000000..2336c22 --- /dev/null +++ b/copywriting/references/platform-character-limits-reference.md @@ -0,0 +1,74 @@ +# Platform Character Limits Reference + +Memorize this. Every character counts in paid media. + +### Google Ads + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Headline | **30 characters** | 15 max per RSA | +| Long headline | **90 characters** | Performance Max | +| Description | **90 characters** | 4 max per RSA | +| Display URL path | **15 characters** each | 2 paths max | +| Callout extension | **25 characters** | | +| Sitelink title | **25 characters** | | +| Sitelink description | **35 characters** per line | 2 lines | +| Structured snippet value | **25 characters** | | + +### Meta/Facebook Ads + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Primary text | **125 characters** visible (2,200 max) | First 125 shown before "See More" | +| Headline | **40 characters** recommended (255 max) | Truncates on mobile around 40 | +| Link description | **30 characters** recommended (255 max) | Often hidden on mobile | +| Ad name (internal) | **255 characters** | Not shown to users | + +### TikTok Ads + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Ad text | **100 characters** recommended (999 max) | First 100 visible | +| Display name | **40 characters** | Brand name shown | +| CTA button | Platform presets only | "Download", "Learn More", "Shop Now" | +| Video | **5-60 seconds** | 15-30s optimal for conversion | + +### Apple App Store (iOS) + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| App name | **30 characters** | Most important ranking factor | +| Subtitle | **30 characters** | Visible in search results | +| Keyword field | **100 characters** | Comma-separated, no spaces after commas | +| Promotional text | **170 characters** | Above description, can change anytime without review | +| Description | **4,000 characters** | Only first 3 lines visible before "more" | +| What's New | **4,000 characters** | Shown on update screen | +| Screenshots | **10 max** | First 3 visible in search (most critical) | + +### Google Play Store (Android) + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| App name | **30 characters** | | +| Short description | **80 characters** | Visible in search results. This is your pitch. | +| Full description | **4,000 characters** | Keyword-indexed (unlike iOS description) | +| What's New | **500 characters** | | +| Screenshots | **8 max** | First 3-4 visible in search | + +### Push Notifications + +| Platform | Title Limit | Body Limit | Notes | +|----------|------------|------------|-------| +| iOS | **~50 characters** visible | **~150 characters** visible | Varies by device/lock screen | +| Android | **65 characters** | **240 characters** | Expanded notification shows more | +| Rich push (iOS) | Same | Same + image/buttons | Requires notification extension | + +### Email + +| Element | Guideline | Notes | +|---------|-----------|-------| +| Subject line | **30-50 characters** optimal | 50% open on mobile, shorter = better | +| Preview text | **40-90 characters** | Shows after subject on most clients | +| CTA button text | **2-5 words** | "Start Investing Free" not "Click Here to Get Started with Our Platform" | + +--- diff --git a/copywriting/references/process-writing-copy-with-this-skill.md b/copywriting/references/process-writing-copy-with-this-skill.md new file mode 100644 index 0000000..f39af23 --- /dev/null +++ b/copywriting/references/process-writing-copy-with-this-skill.md @@ -0,0 +1,13 @@ +# Process: Writing Copy with This Skill + +1. **Identify the format** (App Store, Google Ad, landing page, TikTok script, push, email) +2. **Read WRITING-STYLE.md** for tone calibration +3. **Identify the audience awareness level** (unaware, problem-aware, solution-aware) +4. **Pick the framework** (AIDA for most ads, PAS for pain-heavy audiences, Offer Stack for pricing pages) +5. **Write to the character limits** (reference the table above, write to fit) +6. **Apply the anti-pattern checklist** (feature listing? weak CTA? no social proof? fix it) +7. **Include social proof** (never ship copy without at least one proof element) +8. **Write 3 variants** for A/B testing (different hooks, same structure) +9. **Check against WRITING-STYLE.md** one more time (does it sound like Eric? Would he say this to a friend?) + +--- diff --git a/copywriting/references/quick-reference-cta-library.md b/copywriting/references/quick-reference-cta-library.md new file mode 100644 index 0000000..a2c7d3f --- /dev/null +++ b/copywriting/references/quick-reference-cta-library.md @@ -0,0 +1,18 @@ +# Quick Reference: CTA Library + +Strong CTAs for Bloom, organized by context: + +| Context | CTA | Notes | +|---------|-----|-------| +| App Store | "Download Bloom Free" | Risk reversal built in | +| Google Ad | "Get Bloom — Free Download" | Action + risk reversal | +| Landing page (primary) | "Download Free" | Short, clear, no friction words | +| Landing page (secondary) | "See How It Works" | For not-ready visitors | +| TikTok/Meta | "Link in bio" / "Download now" | Platform native | +| Push notification | "See the analysis →" | Implies content waiting for them | +| Email (free user) | "Research Your Next Stock" | Activity-focused, not upgrade-focused | +| Email (upgrade) | "Get 50% Off Premium" | Specific offer | +| Email (win-back) | "See What You Missed" | Curiosity + FOMO | +| Trial expiring | "Keep Premium" | Loss aversion framing | + +**Never use:** "Learn More", "Click Here", "Submit", "Get Started", "Sign Up Now", "Explore" diff --git a/copywriting/references/quiz-funnel-copy.md b/copywriting/references/quiz-funnel-copy.md new file mode 100644 index 0000000..32ebe5a --- /dev/null +++ b/copywriting/references/quiz-funnel-copy.md @@ -0,0 +1,67 @@ +# Quiz Funnel Copy + +Source: @DTC_Quizbuilder (https://x.com/DTC_Quizbuilder/status/2010379560769015885) + +## When to Use + +When running paid ads to a subscription app and cold traffic conversion is below 2%. A quiz between the ad and the offer warms traffic through micro-commitments and belief-seeding. + +Funnel: Ad → Web Quiz (6-8 questions) → Captive Loading Screen → Personalized Results → App Store / Paywall + +## Quiz Question Copy Rules + +**Q1-Q2: Zero cognitive load.** Age range, gender, experience level. No thinking required. The goal is one click, not one insight. "How old are you?" beats "What's your biggest financial dream?" + +**Q3-Q4: Aspirational.** Now go emotional. "What's your #1 investing goal?" with options like "Build wealth for retirement", "Beat inflation", "Replace my income." These questions seed the desire before they see the product. + +**Q5-Q6: Pain points.** "What's been your biggest challenge with investing?" Options surface objections you'll handle on the results page: "I don't know what to buy", "I always buy at the wrong time", "Too much conflicting information." + +**Option copy:** 4 options max per question. Short (under 8 words each). Always include a catch-all ("None of the above" or "I'm not sure yet"). Decision fatigue kills completion. + +**Breather slides:** After Q4, insert a non-question slide with social proof: "Join 50,000+ investors who use AI to make smarter decisions." Resets cognitive load. Feels like progress. + +## Captive Loading Screen Copy + +The 10-15 seconds while "calculating results" is captive attention. The user can't click away. Use it. + +Show in sequence: +1. Strong testimonial with specific numbers ("Bloom helped me spot the Tesla dip 2 days before the rebound") +2. Social proof stat ("Trusted by X investors") +3. Product preview (screenshot of the app doing the thing they just said they want) + +## Results Page Copy + +The results page IS the sales page. Structure: + +1. **Personalized headline:** "Based on your answers, you're a [Growth-Focused / Conservative / AI-Curious] investor." Mirror their quiz answers back. +2. **Problem restate:** "You told us [pain point from Q5]. Here's why that happens." Use their exact answer. +3. **Solution frame:** "Bloom's AI analyzes [thing] so you don't have to [pain point]." +4. **Social proof:** Testimonial matching their investor type. +5. **CTA:** "Get Your Personalized Plan" → App Store link. + +## Retargeting Copy (Non-Completers) + +Everyone who quit the quiz or didn't convert gave you data. Write retargeting ads that match their last answer: + +| Quiz answer | Retargeting angle | +|-------------|-------------------| +| "I don't know what to invest in" | "Bloom tells you exactly what to buy and when" | +| "I always buy at the wrong time" | "AI that spots entry points before you read about them" | +| "Tried other apps, didn't help" | "Why Bloom's AI is different from [competitor]" | +| "Not enough time to research" | "2 minutes/day. That's all Bloom needs." | + +Specific beats generic. A retargeting ad that says "you told us you struggle with timing" converts better than "download our investing app." + +## Drop-Off Benchmarks + +- Q1: 30-40% drop-off (normal, biggest filter) +- Q2-Q8: Under 15% each +- Overall completion: 25%+ is good +- If any question has 10%+ drop-off: simplify options, reduce choices, add catch-all + +## Bloom-Specific Notes + +Bloom's onboarding already asks risk tolerance and goals post-install. A web quiz version of this flow could: +1. Warm cold traffic before the App Store page +2. Feed retargeting segments even for non-installers +3. Pre-frame the value prop based on the user's self-identified investor type diff --git a/copywriting/references/real-world-examples-finance-investing-apps.md b/copywriting/references/real-world-examples-finance-investing-apps.md new file mode 100644 index 0000000..807d884 --- /dev/null +++ b/copywriting/references/real-world-examples-finance-investing-apps.md @@ -0,0 +1,61 @@ +# Real-World Examples (Finance/Investing Apps) + +### High-Converting App Store Descriptions + +**Robinhood** (what they do well): +- Name: `Robinhood: Investing for All` — clear positioning in the name +- First line: "Invest in stocks, options, and ETFs with Robinhood Financial. Buy and sell crypto with Robinhood Crypto." — immediately tells you what you can DO +- Social proof embedded: "Join over 10 million people" + +**Seeking Alpha** (what they do well): +- Name: `Seeking Alpha: Stock Market` — keyword-rich +- Key line: "What Wall Street Analysts & Financial Experts Are Saying About Your Stocks" — creates FOMO +- Specific value: "4,700+ stocks rated with Quant Rankings" + +**Morningstar** (what they do well): +- Authority positioning: "Independent. Trusted. Transparent." +- Specifics: "Track 620,000+ investments worldwide" + +**What they all share:** Specific numbers. Clear benefits in the first line. Social proof or authority signals. Action-oriented language. + +### High-Converting Google Ad Examples (Finance) + +**Wealthfront:** +``` +Headline: "Invest on Autopilot" +Description: "Set it and forget it. Automated investing with free financial planning. Get your first $5K managed free." +``` +Why it works: Benefit-led headline. Specific offer (first $5K free). Risk reversal (free). + +**Betterment:** +``` +Headline: "Investing Made Better" +Description: "Smart investing without the emotional decisions. Start with as little as $10. No minimum balance." +``` +Why it works: Addresses pain (emotional decisions). Low barrier ($10). Risk reversal (no minimum). + +### Bloom Ad Copy Examples + +**Google Search Ad (targeting "stock research app"):** +``` +Headline 1: AI Stock Research App (21) +Headline 2: Research Stocks in Seconds (26) +Headline 3: Free Download — Bloom (20) +Description 1: Search any stock, get an instant AI breakdown. Analyst ratings, insider trades, earnings — all in one app. (89) +Description 2: 52,000+ investors. 4.8★ rating. AI reads the filings so you don't have to. Download free, no credit card. (90) +``` + +**TikTok Ad (script summary):** +``` +[0-2s] Text: "The app that reads SEC filings for you" + Voice: "I stopped spending hours on stock research." +[2-7s] "I used to have 6 tabs open. Yahoo Finance, SEC.gov, Seeking Alpha..." +[7-15s] "Now I just search any stock in this app and it gives me everything. + Analyst ratings. Insider trades. Bull case. Bear case." + [Show app screen recording] +[15-20s] "4.8 stars, 50K+ investors." +[20-25s] "It's free. Link in bio." + Text: "Bloom — Download Free" +``` + +--- diff --git a/copywriting/references/references.md b/copywriting/references/references.md new file mode 100644 index 0000000..ca88f9f --- /dev/null +++ b/copywriting/references/references.md @@ -0,0 +1,7 @@ +# References + +| File | Contents | +|------|----------| +| `references/copy_frameworks.md` | 14 proven copywriting frameworks (PAS, AIDA, BAB, FAB, ACCA, STAR, etc.) with detailed structures, selection matrix by platform/goal, and when-to-use guidance | +| `references/writing_styles.md` | Voice and tone rules from Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, Collier. Contains banned phrases list, AI tell patterns, and how human copy sounds. | +| `references/lead-magnet-patterns.md` | Lead magnet post structures, value framing techniques, CTA patterns for social giveaway posts | diff --git a/copywriting/references/skill-integration.md b/copywriting/references/skill-integration.md new file mode 100644 index 0000000..fdb9c28 --- /dev/null +++ b/copywriting/references/skill-integration.md @@ -0,0 +1,7 @@ +# Skill Integration + +- **Headlines skill** (`headlines/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). +- **Google Ads skill** (`google-ads/SKILL.md`): Use for campaign management, performance queries, and pausing underperformers. This skill writes the copy; that skill deploys and measures it. +- **Meta Ads skill** (`meta-ads/SKILL.md`): Use for creating/managing Meta ad creatives and measuring performance. + +--- diff --git a/copywriting/references/test-app-store-screenshot-order.md b/copywriting/references/test-app-store-screenshot-order.md new file mode 100644 index 0000000..66b1a2e --- /dev/null +++ b/copywriting/references/test-app-store-screenshot-order.md @@ -0,0 +1,12 @@ +# Test: App Store Screenshot Order + +- Date: 2026-01-15 to 2026-01-29 +- Variants: A (benefit text first) vs B (UI screenshot first) +- Sample: 12,000 impressions each +- Result: A won, 23% higher conversion rate +- Confidence: 97% +- Action: Implemented A as default +- Learning: Benefit text > raw UI for top-of-funnel discovery users +``` + +--- diff --git a/copywriting/references/the-seven-sweeps-copy-editing-framework.md b/copywriting/references/the-seven-sweeps-copy-editing-framework.md new file mode 100644 index 0000000..3796ba5 --- /dev/null +++ b/copywriting/references/the-seven-sweeps-copy-editing-framework.md @@ -0,0 +1,19 @@ +# The Seven Sweeps (Copy Editing Framework) + +After drafting any copy, run these seven sequential editing passes. Each focuses on one dimension. + +1. **Clarity**: Can the reader understand what you're saying? Cut confusing sentences, unclear pronouns, jargon, ambiguity. +2. **Voice & Tone**: Consistent brand voice throughout? Check for shifts between casual and corporate. Read aloud for inconsistencies. +3. **So What**: Does every claim answer "why should I care?" For every feature statement, add the "which means..." bridge to a benefit. +4. **Prove It**: Is every claim supported? Flag unsubstantiated assertions. Add testimonials, stats, case studies, or soften the claim. +5. **Specificity**: Replace vague with concrete. "Save time" → "Save 4 hours every week." "Many customers" → "2,847 teams." Remove anything that can't be made specific (it's filler). +6. **Heightened Emotion**: Does the copy make the reader feel something? Paint the "before" state vividly. Reference shared experiences. +7. **Zero Risk**: Have we removed every barrier to action? Address objections near CTAs. Add trust signals, guarantees, clear next steps. + +After each sweep, loop back to verify previous sweeps aren't compromised. The process is iterative. + +### Quick Word-Level Fixes +**Cut:** very, really, extremely, just, actually, basically, "in order to" +**Replace:** utilize → use, implement → set up, leverage → use, facilitate → help, innovative → new, robust → strong, seamless → smooth + +--- diff --git a/copywriting/references/writing_styles.md b/copywriting/references/writing_styles.md new file mode 100644 index 0000000..5850f50 --- /dev/null +++ b/copywriting/references/writing_styles.md @@ -0,0 +1,233 @@ +# Writing Styles & Voice Reference + +How to write copy that sounds like a human wrote it. Built from the principles of Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, and Collier. + +--- + +## The One Rule That Overrides Everything + +Write like you're talking to one person. Not an audience. One person. The specific person who has the specific problem your product solves. Read every sentence back as if you're saying it out loud to them across a table. + +--- + +## The Legendary Principles + +### Ogilvy: Show, Don't Explain + +"At 60 miles an hour, the loudest noise in this new Rolls-Royce comes from the electric clock." + +He never said "this car is quiet." He showed it through a single detail that made the reader feel the quietness. This is the single most important lesson in copywriting. + +**What this means in practice:** +- Don't say "high quality." Show what high quality looks like in a specific, concrete detail. +- Don't say "easy to use." Describe someone using it in a way that feels effortless. +- Don't say "customers love it." Quote one customer saying one specific thing that only someone who actually used it would say. +- The reader should arrive at your conclusion themselves. Your job is to arrange the details so that conclusion is obvious. + +**Examples:** +- BAD: "Our supplement is made with premium, high-quality ingredients." +- GOOD: "We source our omega-3s from wild-caught mackerel off the coast of Peru. Not farmed. Not blended." + +- BAD: "Our app is incredibly intuitive and easy to use." +- GOOD: "My 67-year-old mother set it up herself. Took her 4 minutes. She texted me a screenshot." + +### Schwartz: Match the Message to Where They Actually Are + +Eugene Schwartz defined 5 levels of awareness. Most copy fails because it writes to someone at the wrong stage. + +| Level | Where they are | What your copy should do | +|-------|----------------|--------------------------| +| Unaware | Don't know they have a problem | Name the problem in a way that makes them go "wait, that's me" | +| Problem-aware | Know they have a problem, don't know solutions exist | Validate the problem. Make them feel less alone. | +| Solution-aware | Know solutions exist, haven't picked one | Show why your solution is different from what they've tried | +| Product-aware | Know your product exists, aren't sure it's for them | Remove objections. Show proof. Make the decision easy. | +| Most aware | Ready to buy, just need the final nudge | Make the CTA frictionless. Remove the last excuse. | + +**Why this matters:** If someone is Problem-Aware and your copy leads with features and specs, they leave immediately. If someone is Most-Aware and your copy starts from scratch explaining the problem, they feel like you're wasting their time. + +### Hopkins: Advertising Is Salesmanship in Print + +Claude C. Hopkins wrote "Scientific Advertising" in 1923. Still relevant. + +His core rules: +- **Lead with "reason why."** Don't just claim something. Explain the mechanism. People are skeptical by default. Give them a reason to believe. +- **Be specific.** "Saves you time" is meaningless. "Saved our users 2.4 hours on average in the first week" is a claim. Specificity = credibility. +- **Test everything.** Assume your first instinct is wrong. Write two versions. The data decides. +- **Speak to the individual.** "Dear Reader" energy, not "Dear Customer" energy. + +### Halbert: The Starving Crowd + +Gary Halbert's golden rule: find the hungry crowd first, then write to them. + +What this means for copy: +- The best copy in the world falls flat if no one who reads it actually has the problem. +- Before writing a single word, ask: who is already desperate for this? What are they already googling at 2am? Write to that moment. +- **Write to one person.** Imagine the single most frustrated version of your customer. Write to them specifically. The copy that works for them works for everyone. + +### Sugarman: The Slippery Slide + +Joseph Sugarman's principle: every element of your copy should pull the reader to the next one. No friction. No stopping points. The headline pulls them to the first sentence. The first sentence pulls them to the second. And so on until they hit the CTA having already said yes in their head. + +**How to apply it:** +- The first sentence of your copy should be the easiest sentence in the world to read. Short. Punchy. Impossible to stop at. +- Don't put a wall of text after your hook. Put one short sentence. +- Each paragraph earns the next one. If a paragraph doesn't pull the reader forward, cut it. +- The CTA should feel like the obvious next step, not a demand. + +### Caples: Headlines Do 80% of the Work + +John Caples tested thousands of headlines. His findings: +- Most people read headlines only. If your headline doesn't hook them, the body copy doesn't exist. +- The strongest headlines create a curiosity gap or a specific promise with a timeframe. +- Odd numbers outperform even numbers. Specific numbers outperform round ones. +- Headlines that self-select ("If you hate Mondays...") outperform broad ones. + +### Collier: Enter the Conversation Already Happening + +Robert Collier's rule: don't start a new conversation. Join the one already happening in your reader's head. + +**In practice:** +- Figure out what they're already thinking about when they see your ad. +- Start your copy from that exact thought. +- If a founder is already frustrated about their team missing deadlines, your first line should reference missed deadlines, not "project management." + +--- + +## AI Tells: The Banned List + +These are patterns that make copy sound like a machine wrote it. Every single one of these kills trust instantly. If you catch yourself writing any of these, stop and rewrite. + +### Banned Phrases (Never Use) +- "And honestly?" +- "It's not X. It's Y." / "This isn't about X. It's about Y." +- "The truth is..." +- "Here's the thing..." +- "At the end of the day..." +- "In today's fast-paced world..." +- "Game-changer" / "game-changing" +- "Let's dive in" / "Let's dive into" +- "Whether you're a X or a Y..." +- "Unlock your potential" +- "Take it to the next level" +- "Seamless experience" +- "Leverage your assets" +- "Streamline your workflow" +- "Revolutionize" +- "Robust" +- "Delve" +- "Empowering" +- "Tailored solutions" +- "Drive results" +- "Synergy" + +### Banned Punctuation Habits +- Em dashes used for dramatic effect. ("Write great copy — or don't bother trying.") Use a period or restructure the sentence instead. +- Multiple exclamation marks. +- Ellipses for fake suspense ("But wait...") + +### Banned Structural Patterns +- Starting a paragraph with "Now," as a transition word. +- Writing three short fragments in a row for "punch." (One fragment for emphasis is fine. Three in a row is a tic.) +- Ending a section with a one-liner that restates what you just said. ("That's how you win.") +- Fake vulnerability openers that are actually humble bragging. ("I almost quit. But I'm glad I didn't, because now I do $50K/month.") +- Listing benefits as a bulleted wall. Three bullets max. If you have more, weave them into sentences. + +### The Em Dash Rule +Em dashes have one job: a brief aside that adds a detail. Use them sparingly, at most once per paragraph. Never use them to build drama. Never use them twice in the same sentence. + +WRONG: "This tool — unlike anything else on the market — will completely change — the way you work." +RIGHT: "This tool will completely change the way you work. Nothing else comes close." + +--- + +## What Human Copy Actually Sounds Like + +### Use Contractions +"You are going to love this" sounds corporate. "You're going to love this" sounds like a person. + +### Use Fragments. Intentionally. +"Best part? It's free." This is a fragment. It works because it feels like speech. + +### Use "I" and "You" Freely +Good copy is a conversation between two people. "I" and "You" should appear in almost every paragraph. + +### Have Opinions +"Most project management tools are bloated garbage." This is an opinion. It's also a hook. Bland copy has no opinions. Good copy has strong ones. + +### Admit Limitations +"This won't work if you need X." Saying what your product can't do builds more trust than pretending it does everything. The reader respects honesty and stops being skeptical. + +### Use Sensory and Specific Details +"The dashboard loads in 0.8 seconds" is specific. "Lightning fast" is meaningless. Specificity is the fastest way to sound credible and human at the same time. + +### Revenue and Number Transparency +Sharing real numbers makes copy feel authentic. "$45,000/month in revenue" is a real claim. "Six figures" is vague and suspicious. + +--- + +## How to Structure Sentences That Sell + +### Short First. Long Second. +Open with a short sentence. Follow with a longer one that explains. This is how humans actually talk. + +GOOD: +"I wasted 6 months building the wrong product. I had a great idea, a solid team, and zero customers by the end." + +BAD: +"After spending approximately six months developing what I believed to be an innovative solution, I found myself confronted with the uncomfortable reality of having attracted zero customer interest." + +### Vary Your Sentence Length +Read your copy out loud. If every sentence is the same length, it sounds like a robot. Mix short punchy ones with longer ones that build. + +### The Specific Detail Over the Adjective +INSTEAD OF: "incredibly effective marketing strategy" +WRITE: "the marketing strategy that brought in 340 leads in 11 days" + +INSTEAD OF: "a user-friendly interface" +WRITE: "the whole thing fits on one screen. No menus, no dropdowns." + +--- + +## CTAs That Actually Work + +Don't say: "Sign Up" / "Submit" / "Learn More" / "Click Here" + +Say what happens when they click: +- "Get the free template" +- "See my first 30 days" +- "Start your free trial" +- "Download the guide" +- "Book a 15-minute call" + +Add a friction reducer after the CTA: +- "No credit card needed." +- "Takes 2 minutes to set up." +- "Cancel anytime." +- "See results in 14 days or your money back." + +--- + +## Testimonial Format That Works + +A testimonial with structure converts. A vague one doesn't. + +WEAK: "Great product, highly recommend!" + +STRONG FORMAT: [Before state] + [Specific action taken] + [Specific result] + [Timeframe] + [Emotion or implication] + +STRONG: "I was getting 12 leads a month from cold outreach. Started using the new templates on a Tuesday. By Friday I had 4 booked calls. Didn't change anything else." + +--- + +## Quick Sanity Check Before Finalizing + +Read the copy out loud. If any of these are true, rewrite: +- You stumbled over a sentence (it's too complicated) +- You felt bored halfway through (it's not pulling you forward — Sugarman's slippery slide is broken) +- You heard any of the Banned Phrases +- You saw an em dash used for drama +- You couldn't find a single opinion or specific number +- It could have been written about any product (it's not specific enough) +- It sounds like it was written by someone trying to sound smart (it wasn't written to sell) + +--- diff --git a/email-sequence/SKILL.md b/email-sequence/SKILL.md index e5de6f0..f090560 100644 --- a/email-sequence/SKILL.md +++ b/email-sequence/SKILL.md @@ -11,7 +11,7 @@ Design lifecycle messaging sequences: email, push notifications, or both. ## Before Starting -Read `product-marketing-context.md` in the workspace root if it exists. +Read `.agents/product-marketing-context.md` if it exists. Gather this context (ask if not provided): diff --git a/email-sequence/references/copy-guidelines.md b/email-sequence/references/copy-guidelines.md index 80c97b1..7eab2dd 100644 --- a/email-sequence/references/copy-guidelines.md +++ b/email-sequence/references/copy-guidelines.md @@ -1,19 +1,19 @@ -# Copy Guidelines (Bloom) +# Copy Guidelines -Guidelines for writing push notifications and email copy for Bloom's lifecycle messaging. +Guidelines for writing push notifications and email copy for lifecycle messaging. --- -## Bloom's Voice +## Brand Voice - Direct, not corporate - Helpful, not salesy - Confident, not hype-y -- Treats users as smart investors, not beginners (unless they are) -- No AI slop patterns (see SOUL.md for the full kill list) +- Treats users as capable adults, not beginners (unless they are) +- No AI slop patterns (vague superlatives, filler phrases, hollow enthusiasm) -**Do:** "Your watchlist stock AAPL is up 3% today." -**Don't:** "Great news! 🎉 We're thrilled to let you know that your amazing portfolio has some exciting updates!" +**Do:** "Your tracked item dropped to $49 today." +**Don't:** "Great news! 🎉 We're thrilled to let you know that your amazing account has some exciting updates!" --- @@ -32,42 +32,42 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m ### Patterns That Work **Data-driven:** -- "[Stock] is up 5% today" (specific, relevant) -- "Your portfolio gained $X this week" (personalized) -- "3 of your stocks hit new highs" (aggregated insight) +- "[Item] hit your target price" (specific, relevant) +- "You reached your weekly goal" (personalized milestone) +- "3 of your tracked items have updates" (aggregated insight) **Feature education:** -- "Ask Bloom about any stock" (clear, actionable) -- "Connect your brokerage to track everything" (specific benefit) +- "Ask [Product] any question" (clear, actionable) +- "Connect your account to track everything" (specific benefit) -**FOMO (use sparingly):** -- "[Stock] just reported earnings. See the analysis." (timely) -- "Markets opened down 2%. Your watchlist update is ready." (relevant) +**Timely:** +- "[Event] just happened. See the summary." (timely) +- "Weekly update is ready." (relevant) ### Patterns to Avoid - Generic: "Check out what's new!" (no reason to tap) - Desperate: "We miss you! Come back!" (cringe) -- Clickbait: "You won't believe what happened to your stock!" (breaks trust) -- Guilt: "Your watchlist is lonely" (manipulative) +- Clickbait: "You won't believe what happened!" (breaks trust) +- Guilt: "Your account feels lonely" (manipulative) - Too frequent: More than 1 push per day for non-urgent content (push fatigue) ### Emoji in Push - One emoji max per push, and only if it adds meaning -- ✅ "📊 AAPL earnings are out" (emoji adds context) -- ❌ "🎉🚀💰 Your portfolio is up!!!" (emoji spam) +- ✅ "📊 Your report is ready" (emoji adds context) +- ❌ "🎉🚀💰 Great things happening!!!" (emoji spam) --- -## Email Copy (Future) +## Email Copy ### Structure 1. **Hook**: First line grabs attention (no "Hi [Name], I hope you're well") 2. **Context**: Why this matters to them 3. **Value**: The useful content 4. **CTA**: What to do next (one primary CTA per email) -5. **Sign-off**: Simple. "— Bloom" is fine. +5. **Sign-off**: Simple. "— [Product Name]" is fine. ### Length - Transactional (billing, alerts): 50-100 words @@ -79,13 +79,13 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m - 40-60 characters - Clear > clever - Specific > vague -- Personalized when possible ("[Stock] moved X% today") +- Personalized when possible ("[Item] moved X% today") **Patterns that work:** -- Data: "Your portfolio is up 8% this month" -- Question: "Have you tried AI stock analysis?" -- Direct: "Payment issue with your Bloom subscription" -- Update: "New in Bloom: [feature name]" +- Data: "You hit your goal this month" +- Question: "Have you tried [feature]?" +- Direct: "Payment issue with your subscription" +- Update: "New in [Product]: [feature name]" **Patterns to avoid:** - Vague: "Important update" (about what?) @@ -101,7 +101,7 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m ### CTA Guidelines - One primary CTA per email (button) -- Button text: Action verb + destination ("See Full Report", "Update Payment", "Add a Stock") +- Button text: Action verb + destination ("See Full Report", "Update Payment", "Add an Item") - Links for secondary actions (in-text) - Every CTA deep links to the relevant app screen or web page @@ -110,21 +110,21 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m ## Personalization ### Data to Use -- Stock names from their watchlist -- Portfolio performance numbers -- Feature usage stats (insights received, stocks tracked) +- Names or identifiers from their profile (items tracked, activity) +- Performance numbers or stats relevant to them +- Feature usage patterns (actions taken, content consumed) - Subscription tenure - Platform (iOS/Android) for correct settings deep links ### Dynamic Content - Personalize based on segment (free vs. paid, new vs. long-term) - Personalize based on behavior (active vs. dormant, features used) -- Personalize based on their actual data (watchlist, portfolio) +- Personalize based on their actual data (tracked items, history) ### Fallbacks -- No watchlist data? Use market index data instead +- No user-specific data? Use aggregate or default content - No name? Skip the greeting or use "there" -- No portfolio? Focus on watchlist or discovery features +- No activity data? Focus on feature discovery --- @@ -157,7 +157,7 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m - Sequence: timing between messages, number of messages, exit conditions ### How to Test -- Use PostHog feature flags for A/B tests +- Use feature flags for A/B tests - One variable at a time - Sufficient sample size before declaring a winner - Document every test and result @@ -165,12 +165,12 @@ Guidelines for writing push notifications and email copy for Bloom's lifecycle m ### Metrics to Track **Push:** -- Delivery rate (expect low due to token staleness) +- Delivery rate (expect some loss due to token staleness) - Open/tap rate (5-15% is normal for mobile push) - Conversion rate (action taken after tap) - Opt-out rate (keep under 0.5% per push) -**Email (future):** +**Email:** - Open rate (target: 25-40%) - Click rate (target: 3-5%) - Unsubscribe rate (keep under 0.5%) diff --git a/evaluate-content/SKILL.md b/evaluate-content/SKILL.md index 57f8822..a550a44 100644 --- a/evaluate-content/SKILL.md +++ b/evaluate-content/SKILL.md @@ -145,7 +145,7 @@ TRIM: [paragraph/sentence] → [shorter version] - **The reader** in one sentence: "A 28-year-old PM who just got assigned to an AI product and has no idea what evals are." - **Their trigger**: What happened that made them need this? "Their AI shipped a wrong answer and the CEO noticed." - **What they'd Google**: The search query that would lead to this. "how to test AI product quality" -- **Their awareness level** (from hooks skill): +- **Their awareness level** (from headlines skill): - Unaware: doesn't know the problem exists - Problem-aware: knows the problem, doesn't know the solution - Solution-aware: knows solutions exist, comparing options @@ -473,6 +473,66 @@ Use these for faster reviews when a full seven-sweep process isn't needed. | Seamless | Smooth | | Cutting-edge | New/Modern | +### Plain English Alternatives + +Replace complex or pompous words with simpler ones. Source: Plain English Campaign, plainlanguage.gov. + +| Complex | Plain | +|---------|-------| +| absence of | no, none | +| accomplish | do, finish | +| additional | extra, more | +| advise | tell, say | +| allocate | give, share | +| anticipate | expect | +| approximately | about | +| ascertain | find out | +| assistance | help | +| at the present time | now | +| cease | stop, end | +| commence | start, begin | +| communicate | tell, talk | +| consequently | so | +| currently | now | +| demonstrate | show, prove | +| determine | decide | +| discontinue | stop | +| disseminate | spread | +| due to the fact that | because | +| endeavour | try | +| establish | set up, show | +| expedite | speed up | +| facilitate | help | +| for the purpose of | to, for | +| furthermore | also, and | +| implement | carry out, do | +| in accordance with | under | +| in conjunction with | with | +| in order to | to | +| in the event of | if | +| indicate | show, suggest | +| initiate | start, begin | +| moreover | also, and | +| notify | tell | +| obtain | get | +| on behalf of | for | +| owing to | because | +| permit | let, allow | +| prior to | before | +| procure | get | +| provide | give | +| purchase | buy | +| regarding | about | +| reimburse | repay | +| require | need | +| retain | keep | +| subsequently | later | +| sufficient | enough | +| terminate | end, stop | +| utilise | use | + +**Phrases to remove entirely:** "a total of," "absolutely," "actually," "at the end of the day," "at this moment in time," "basically," "I am of the opinion that" (use "I think"), "in the final analysis," "it should be understood," "last but not least," "obviously," "of course," "quite," "really," "the fact of the matter is," "to all intents and purposes," "very." + **Watch for:** - Adverbs (usually unnecessary) - Passive voice (switch to active) @@ -588,6 +648,6 @@ Use all three levels together. A great post (high individual score) in a dying p - Used by **article-writer** (revision pass) - Used by **typefully** (hook quality check) - Used by **tweet-ideas** (tweet quality) -- Used by **hooks** (title evaluation) +- Used by **headlines** (title evaluation) - Shares voice standards with **article-writer** humanizer section - **`~/marketing/WRITING-STYLE.md`** — ground truth for voice evaluation. Read the Kill Phrases list and Voice Fingerprint section before scoring Question 3. Generic "sounds human" is not the bar; Eric's specific fingerprint is. diff --git a/growth/SKILL.md b/growth/SKILL.md index ad95924..c7a8ef0 100644 --- a/growth/SKILL.md +++ b/growth/SKILL.md @@ -19,16 +19,21 @@ You are an expert in SaaS growth — both in-product conversion rate optimizatio | **Onboarding** | Post-signup activation, first-run experience, time-to-value | | **Paywall** | In-app upgrade screens, feature gates, trial expiration | | **Retention** | Cancel flows, save offers, dunning, win-back | -| **Launches** | Product launches, feature releases, Product Hunt, go-to-market | -| **Pricing** | Tiers, packaging, value metrics, price increases, monetization | -| **Email** | Drip campaigns, welcome sequences, nurture, re-engagement | -| **Referrals** | Referral programs, affiliates, viral loops, word-of-mouth | +| **Page CRO** | Landing page, homepage, pricing page, feature page conversion optimization | +| **Form CRO** | Lead capture forms, contact forms, demo request forms, checkout forms | +| **Popup CRO** | Exit intent, email capture popups, modals, slide-ins, announcement banners | +| **Launches** | Product launches, feature releases, Product Hunt, go-to-market. For detailed help, use the **launch-strategy** skill. | +| **Pricing** | Tiers, packaging, value metrics, price increases, monetization. For detailed help, use the **pricing-strategy** skill. | +| **Email** | Drip campaigns, welcome sequences, nurture, re-engagement. For detailed help, use the **email-sequence** skill. | +| **Referrals** | Referral programs, affiliates, viral loops, word-of-mouth. For detailed help, use the **referral-program** skill. | +| **Cold Outreach** | B2B cold email sequences, SDR prospecting, outbound campaigns. For detailed help, use the **cold-email** skill. | +| **Paid Ads** | Google Ads, Meta, LinkedIn, paid acquisition strategy. For detailed help, use the **paid-ads** skill. | | **Experimentation** | A/B tests, hypothesis design, sample sizing, analysis | | **Psychology** | Mental models, cognitive biases, persuasion, behavioral science | ## Before Starting -Check `~/clawd/SOUL.md` and `~/clawd/USER.md` for product context. +Read `.agents/product-marketing-context.md` if it exists — it contains product-specific context (name, audience, positioning). --- @@ -521,3 +526,9 @@ See `references/ab-test-sample-size.md` and `references/ab-test-templates.md`. **Design**: Hick's Law (fewer choices = faster decisions), BJ Fogg (Behavior = Motivation × Ability × Prompt), EAST (Easy, Attractive, Social, Timely) For full model descriptions with marketing applications, see `references/psychology-models.md`. + +--- + +# CRO Deep Dives + +For detailed frameworks on page CRO (7-dimension audit), signup flow optimization (social auth, password UX, mobile), onboarding (checklists, empty states, stalled users), paywall screens (templates, timing rules, anti-patterns), form CRO (field optimization, multi-step, error handling, submit buttons), and popup CRO (triggers, types, frequency capping, compliance), see `references/cro-frameworks.md`. diff --git a/growth/references/cro-frameworks.md b/growth/references/cro-frameworks.md new file mode 100644 index 0000000..8bb8a15 --- /dev/null +++ b/growth/references/cro-frameworks.md @@ -0,0 +1,385 @@ +# CRO Frameworks Reference + +Detailed conversion rate optimization frameworks for pages, signup flows, onboarding, paywalls, forms, and popups. Use this alongside the growth skill's core CRO stages. + +--- + +## Page CRO: 7-Dimension Audit Framework + +Analyze any marketing page across these dimensions, in order of impact: + +### 1. Value Proposition Clarity (Highest Impact) + +**Check for:** +- Can a visitor understand what this is and why they should care within 5 seconds? +- Is the primary benefit clear, specific, and differentiated? +- Is it written in the customer's language (not company jargon)? + +**Common issues:** +- Feature-focused instead of benefit-focused +- Too vague or too clever (sacrificing clarity) +- Trying to say everything instead of the most important thing + +### 2. Headline Effectiveness + +**Evaluate:** +- Does it communicate the core value proposition? +- Is it specific enough to be meaningful? +- Does it match the traffic source's messaging? + +**Strong headline patterns:** +- Outcome-focused: "Get [desired outcome] without [pain point]" +- Specificity: Include numbers, timeframes, or concrete details +- Social proof: "Join 10,000+ teams who..." + +### 3. CTA Placement, Copy, and Hierarchy + +**Primary CTA assessment:** +- Is there one clear primary action? +- Is it visible without scrolling? +- Does the button copy communicate value, not just action? + - Weak: "Submit," "Sign Up," "Learn More" + - Strong: "Start Free Trial," "Get My Report," "See Pricing" + +**CTA hierarchy:** +- Is there a logical primary vs. secondary CTA structure? +- Are CTAs repeated at key decision points? + +### 4. Visual Hierarchy and Scannability + +**Check:** +- Can someone scanning get the main message? +- Are the most important elements visually prominent? +- Is there enough white space? +- Do images support or distract from the message? + +### 5. Trust Signals and Social Proof + +**Types to look for:** +- Customer logos (especially recognizable ones) +- Testimonials (specific, attributed, with photos) +- Case study snippets with real numbers +- Review scores and counts +- Security badges (where relevant) + +**Placement:** Near CTAs and after benefit claims. + +### 6. Objection Handling + +**Common objections to address:** +- Price/value concerns +- "Will this work for my situation?" +- Implementation difficulty +- "What if it doesn't work?" + +**Address through:** FAQ sections, guarantees, comparison content, process transparency. + +### 7. Friction Points + +**Look for:** +- Too many form fields +- Unclear next steps +- Confusing navigation +- Required information that shouldn't be required +- Mobile experience issues +- Long load times + +### Page-Specific Frameworks + +**Homepage CRO:** Clear positioning for cold visitors. Quick path to most common conversion. Handle both "ready to buy" and "still researching." + +**Landing Page CRO:** Message match with traffic source. Single CTA (remove navigation if possible). Complete argument on one page. + +**Pricing Page CRO:** Clear plan comparison. Recommended plan indication. Address "which plan is right for me?" anxiety. + +**Feature Page CRO:** Connect feature to benefit. Use cases and examples. Clear path to try/buy. + +**Blog Post CRO:** Contextual CTAs matching content topic. Inline CTAs at natural stopping points. + +--- + +## Signup Flow CRO + +### Social Auth Options +- Place prominently (often higher conversion than email) +- Show most relevant options for your audience + - B2C: Google, Apple, Facebook + - B2B: Google, Microsoft, SSO +- Clear visual separation from email signup +- Consider "Sign up with Google" as primary + +### Password UX +- Show password toggle (eye icon) +- Show requirements upfront, not after failure +- Allow paste (don't disable) +- Show strength meter instead of rigid rules +- Consider passwordless options + +### Mobile Signup Optimization +- Larger touch targets (44px+ height) +- Appropriate keyboard types (email, tel, etc.) +- Autofill support +- Reduce typing (social auth, pre-fill) +- Single column layout +- Sticky CTA button + +### Post-Submit Experience + +**Success state:** +- Clear confirmation +- Immediate next step +- If email verification required: explain what to do, easy resend, check spam reminder, option to change email + +**Verification flows:** +- Consider delaying verification until necessary +- Magic link as alternative to password +- Let users explore while awaiting verification + +### Common Signup Flow Patterns + +| Pattern | Steps | +|---------|-------| +| B2B SaaS Trial | Email + Password (or Google auth) → Name + Company → Onboarding flow | +| B2C App | Google/Apple auth OR Email → Product experience → Profile completion later | +| Waitlist/Early Access | Email only → Optional: Role/use case question → Confirmation | +| E-commerce Account | Guest checkout as default → Account creation optional post-purchase | + +--- + +## Onboarding CRO + +### Defining Activation + +**Find your aha moment:** The action that correlates most strongly with retention. What do retained users do that churned users don't? + +**Examples by product type:** +- Project management: Create first project + add team member +- Analytics: Install tracking + see first report +- Design tool: Create first design + export/share +- Marketplace: Complete first transaction + +### Onboarding Flow Design + +| Approach | Best For | Risk | +|----------|----------|------| +| Product-first | Simple products, B2C, mobile | Blank slate overwhelm | +| Guided setup | Products needing personalization | Adds friction before value | +| Value-first | Products with demo data | May not feel "real" | + +### Onboarding Checklist Pattern (3-7 items) +- Order by value (most impactful first) +- Start with quick wins +- Progress bar/completion % +- Celebration on completion +- Dismiss option (don't trap users) + +### Empty States +Empty states are onboarding opportunities, not dead ends. + +**Good empty state:** +- Explains what this area is for +- Shows what it looks like with data +- Clear primary action to add first item +- Optional: Pre-populate with example data + +### Tooltips and Guided Tours +- Max 3-5 steps per tour +- Dismissable at any time +- Don't repeat for returning users + +### Handling Stalled Users + +**Detection:** Define "stalled" criteria (X days inactive, incomplete setup) + +**Re-engagement tactics:** +1. Email sequence: reminder of value, address blockers, offer help +2. In-app recovery: welcome back, pick up where left off +3. Human touch: for high-value accounts, personal outreach + +### Common Patterns by Product Type + +| Product Type | Key Steps | +|--------------|-----------| +| B2B SaaS | Setup wizard → First value action → Team invite → Deep setup | +| Marketplace | Complete profile → Browse → First transaction → Repeat loop | +| Mobile App | Permissions → Quick win → Push setup → Habit loop | +| Content Platform | Follow/customize → Consume → Create → Engage | + +--- + +## Paywall & Upgrade CRO + +### Paywall Screen Templates + +**Feature Lock Paywall:** +``` +[Lock Icon] +This feature is available on Pro + +[Feature preview/screenshot] + +[Feature name] helps you [benefit]: +• [Capability] +• [Capability] + +[Upgrade to Pro - $X/mo] +[Maybe Later] +``` + +**Usage Limit Paywall:** +``` +You've reached your free limit + +[Progress bar at 100%] + +Free: 3 projects | Pro: Unlimited + +[Upgrade to Pro] [Delete a project] +``` + +**Trial Expiration Paywall:** +``` +Your trial ends in 3 days + +What you'll lose: +• [Feature used] +• [Data created] + +What you've accomplished: +• Created X projects + +[Continue with Pro] +[Remind me later] [Downgrade] +``` + +### Timing Rules +- Show after value moment, before frustration +- After activation/aha moment +- When hitting genuine limits +- NOT during onboarding (too early) +- NOT when they're in a flow +- NOT repeatedly after dismissal +- Limit per session, cool-down after dismiss (days, not hours) + +### Anti-Patterns to Avoid + +**Dark patterns:** Hiding the close button, confusing plan selection, guilt-trip copy. + +**Conversion killers:** Asking before value delivered, too frequent prompts, blocking critical flows, complicated upgrade process. + +--- + +## Form CRO + +### Field Cost Rule of Thumb +- 3 fields: Baseline +- 4-6 fields: 10-25% reduction +- 7+ fields: 25-50%+ reduction + +For each field, ask: Is this absolutely necessary? Can we get this another way? Can we ask this later? + +### Field Order +1. Start with easiest fields (name, email) +2. Build commitment before asking more +3. Sensitive fields last (phone, company size) +4. Logical grouping if many fields + +### Labels and Placeholders +- Labels: Keep visible (not just placeholder). Placeholders disappear when typing, leaving users unsure what they're filling in. +- Placeholders: Examples, not labels +- Help text: Only when genuinely helpful + +### Multi-Step Forms +- Progress indicator (step X of Y) +- Start with easy, end with sensitive +- One topic per step +- Allow back navigation +- Save progress (don't lose data on refresh) + +### Submit Button Optimization + +**Button copy:** +- Weak: "Submit" / "Send" +- Strong: "[Action] + [What they get]" +- Examples: "Get My Free Quote," "Download the Guide," "Request Demo" + +### Error Handling +- Validate as they move to next field (not while typing) +- Clear visual indicators (green check, red border) +- Specific error messages near the field +- Don't clear form on error +- Focus on first error field on submit + +### Form Types: Specific Guidance + +| Type | Key Recommendations | +|------|-------------------| +| Lead Capture | Minimum fields (often just email), clear value prop for what they get | +| Contact Form | Email/Name + Message essential, phone optional, set response time expectations | +| Demo Request | Name, Email, Company required; phone optional with "preferred contact" choice | +| Quote/Estimate | Multi-step works well; start easy, technical details later | +| Survey | Progress bar essential, one question per screen, skip logic | + +--- + +## Popup CRO + +### Trigger Strategies + +| Trigger | When | Best For | +|---------|------|----------| +| Time-based | After 30-60 seconds (not 5 seconds) | General site visitors | +| Scroll-based | 25-50% scroll depth | Blog posts, long-form content | +| Exit intent | Cursor moving to close/leave | E-commerce, lead gen | +| Click-triggered | User initiates (clicks button/link) | Lead magnets, gated content, demos | +| Page count | After visiting X pages | Multi-page journeys | +| Behavior-based | Cart abandonment, pricing page visits | High-intent segments | + +### Popup Types + +**Email Capture:** Clear value prop (not just "Subscribe"), specific benefit, single field, consider incentive. + +**Lead Magnet:** Show what they get (cover image, preview), specific tangible promise, minimal fields. + +**Discount/Promotion:** Clear discount amount, deadline creates urgency, single use per visitor. + +**Exit Intent:** Acknowledge they're leaving, different offer than entry popup, address common objections. + +**Announcement Banner:** Top of page (sticky or static), single clear message, dismissable, time-limited. + +**Slide-In:** Enters from corner/bottom, doesn't block content, easy to dismiss. + +### Copy Formulas + +**Headlines:** +- Benefit-driven: "Get [result] in [timeframe]" +- Question: "Want [desired outcome]?" +- Social proof: "Join [X] people who..." +- Curiosity: "The one thing [audience] always get wrong about [topic]" + +**CTA buttons:** +- First person works: "Get My Discount" vs "Get Your Discount" +- Specific: "Send Me the Guide" vs "Submit" +- Value-focused: "Claim My 10% Off" vs "Subscribe" + +**Decline options:** +- Polite, not guilt-trippy: "No thanks" / "Maybe later" / "I'm not interested" +- Avoid manipulative: "No, I don't want to save money" + +### Frequency and Rules +- Show maximum once per session +- Remember dismissals (cookie/localStorage) +- 7-30 days before showing again +- Exclude checkout/conversion flows +- Match offer to page context +- Exclude converted users + +### Compliance and Accessibility +- GDPR: Clear consent language, link to privacy policy, don't pre-check opt-ins +- Accessibility: Keyboard navigable (Tab, Enter, Esc), focus trap while open, screen reader compatible +- Google: Intrusive interstitials hurt SEO, mobile especially sensitive + +### Benchmarks +- Email popup: 2-5% conversion typical +- Exit intent: 3-10% conversion +- Click-triggered: 10%+ (self-selected audience) diff --git a/launch-strategy/SKILL.md b/launch-strategy/SKILL.md new file mode 100644 index 0000000..d5a90a7 --- /dev/null +++ b/launch-strategy/SKILL.md @@ -0,0 +1,136 @@ +--- +name: launch-strategy +description: "When the user wants to plan a product launch, feature announcement, or release strategy. Use when someone mentions 'launch,' 'Product Hunt,' 'feature release,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'launch checklist.'" +metadata: + version: 1.0.0 +--- + +# Launch Strategy + +Expert in SaaS product launches and feature announcements. Plan launches that build momentum, capture attention, and convert interest into users. + +## Before Starting + +Read `.agents/product-marketing-context.md` if it exists — it contains product name, audience, and positioning context. + +--- + +## Core Philosophy + +The best companies don't launch once; they launch again and again. Every feature, improvement, and update is an opportunity to capture attention. + +--- + +## The ORB Framework + +Structure launch marketing across three channel types. Everything funnels back to owned. + +### Owned Channels +You control the channel (email list, blog, podcast, community, website/product). Get more effective over time. No algorithm changes. + +Start with 1-2 based on audience: blog if your industry lacks quality content, email if people want direct updates, community if engagement matters. + +### Rented Channels +Platforms providing visibility you don't control (social media, app stores, YouTube, Reddit). Pick 1-2 where your audience is active. Use them to drive traffic to owned channels. + +### Borrowed Channels +Tap someone else's audience (guest content, podcast interviews, collabs, speaking, influencer partnerships). Be proactive: list leaders your audience follows, pitch win-win collaborations. + +--- + +## Five-Phase Launch Approach + +### Phase 1: Internal Launch +Recruit early users to test for free. Collect feedback on usability gaps. Validate core functionality. + +### Phase 2: Alpha Launch +Create landing page with early access signup. Announce the product exists. Invite users individually. + +### Phase 3: Beta Launch +Work through early access list. Start marketing with teasers. Recruit friends, investors, influencers. Consider waitlist, "Beta" UI sticker, email invites. + +### Phase 4: Early Access Launch +Leak screenshots, GIFs, demos. Gather quantitative and qualitative data. Optionally run product/market fit survey. Expand via batch invites or open early access. + +### Phase 5: Full Launch +Open self-serve signups. Start charging. Announce across all channels. + +**Launch touchpoints:** Customer emails, in-app popups, website banner, blog post, social posts, Product Hunt, BetaList, Hacker News, onboarding email sequence. + +--- + +## Product Hunt Launch Strategy + +### Before Launch Day +1. Build relationships with supporters and communities +2. Optimize listing: compelling tagline, polished visuals, short demo video +3. Study successful launches +4. Engage in communities before pitching + +### Launch Day +1. Treat it as an all-day event +2. Respond to every comment in real-time +3. Encourage existing audience to engage +4. Direct traffic back to your site for signups + +### After Launch +1. Follow up with everyone who engaged +2. Convert PH traffic into owned relationships (email signups) +3. Continue momentum with post-launch content + +--- + +## Post-Launch Product Marketing + +### Immediate Actions +- Automated onboarding email sequence +- Include announcement in roundup emails +- Publish comparison pages vs. competitors +- Create interactive demo (Navattic-style) +- Add feature sections across website + +### Ongoing Strategy + +**Major updates:** Full campaign across multiple channels. +**Medium updates:** Targeted announcement to relevant segments. +**Minor updates:** Changelog and release notes. + +Space out releases to maintain momentum. Signal active development to build retention. + +--- + +## Launch Checklist + +### Pre-Launch +- [ ] Landing page with clear value proposition +- [ ] Email capture / waitlist +- [ ] Early access list built +- [ ] Owned channels established +- [ ] Launch assets created (screenshots, demo video, GIFs) +- [ ] Onboarding flow ready +- [ ] Analytics/tracking in place + +### Launch Day +- [ ] Announcement email to list +- [ ] Blog post published +- [ ] Social posts scheduled and posted +- [ ] Product Hunt listing live (if using) +- [ ] In-app announcement for existing users +- [ ] Team ready to engage and respond + +### Post-Launch +- [ ] Onboarding email sequence active +- [ ] Follow-up with engaged prospects +- [ ] Comparison pages published +- [ ] Feedback gathered and acted on +- [ ] Plan next launch moment + +--- + +## Related Skills + +- **content-strategy**: For planning launch content +- **email-sequence**: For launch and onboarding email sequences +- **growth**: For optimizing launch landing pages, signup flows +- **marketing-psychology**: For psychology behind waitlists and exclusivity +- **seo-research**: For comparison pages diff --git a/marketing-psychology/SKILL.md b/marketing-psychology/SKILL.md new file mode 100644 index 0000000..349d912 --- /dev/null +++ b/marketing-psychology/SKILL.md @@ -0,0 +1,166 @@ +--- +name: marketing-psychology +description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Use when someone mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'anchoring,' 'social proof,' 'scarcity,' 'loss aversion,' 'framing,' or 'nudge.'" +metadata: + version: 1.0.0 +--- + +# Marketing Psychology & Mental Models + +Expert in applying psychological principles and mental models to marketing. Understand why people buy, influence behavior ethically, and make better marketing decisions. + +## How to Use + +When helping users: +1. Identify which mental models apply to their situation +2. Explain the psychology behind the model +3. Provide specific marketing applications +4. Suggest how to implement ethically + +--- + +## Foundational Thinking Models + +### First Principles +Break problems down to basic truths and build solutions from there. Don't assume you need content marketing because competitors do. Ask why you need it and whether there's a better solution. + +### Jobs to Be Done +People don't buy products; they "hire" them to get a job done. A drill buyer doesn't want a drill; they want a hole. Frame your product around the job it accomplishes. + +### Inversion +Instead of "How do I succeed?", ask "What would guarantee failure?" Then avoid those things. List everything that would make your campaign fail, then systematically prevent each. + +### Pareto Principle (80/20 Rule) +80% of results come from 20% of efforts. Find the 20% of channels, customers, or content driving 80% of results. + +### Theory of Constraints +Every system has one bottleneck. If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first. + +### Second-Order Thinking +Consider effects of effects. A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order). + +### Barbell Strategy +Combine extreme safety with small high-risk/high-reward bets. Put 80% of budget into proven channels, 20% into experiments. + +--- + +## Understanding Buyers + +### Loss Aversion +Losses feel roughly twice as painful as equivalent gains. Frame in terms of what they'll lose by not acting. + +### Endowment Effect +People value things more once they own them. Free trials and freemium models let customers "own" the product. + +### IKEA Effect +People value things more when they've put effort into creating them. Let customers customize or build something. + +### Zero-Price Effect +"Free" triggers irrational preference. Free tiers, free trials, and free shipping have disproportionate appeal. + +### Status-Quo Bias +Change requires effort and feels risky. Make the transition feel safe: "Import your data in one click." + +### Paradox of Choice +Too many options overwhelm. Three pricing tiers beat seven. Recommend a single "best for most" option. + +### Goal-Gradient Effect +People accelerate effort as they approach a goal. Show progress bars and "almost there" messaging. + +### Zeigarnik Effect +Unfinished tasks occupy the mind. "You're 80% done" creates pull to finish. + +### Pratfall Effect +Admitting a weakness increases trust. "We're not the cheapest, but..." + +### Mental Accounting +People treat money differently based on framing. "$3/day" feels different than "$90/month." + +### Social Proof / Bandwagon Effect +People follow what others are doing. Show customer counts, testimonials, logos, reviews. + +### Mere Exposure Effect +Familiarity breeds liking. Consistent brand presence builds preference over time. + +--- + +## Influencing Behavior + +### Reciprocity +Give first, and people want to give back. Free content, tools, and generous free tiers create obligation. + +### Commitment & Consistency +Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next. + +### Authority Bias +People defer to experts. Feature endorsements, certifications, "featured in" logos. + +### Scarcity / Urgency +Limited availability increases perceived value. Only use when genuine. + +### Anchoring Effect +The first number people see heavily influences judgments. Show the higher price first. + +### Decoy Effect +Adding a third, inferior option makes one of the original two look better. + +### Framing Effect +"90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively. + +### BJ Fogg Behavior Model +Behavior = Motivation x Ability x Prompt. All three must be present for action. + +### EAST Framework +Make desired behaviors: Easy, Attractive, Social, Timely. + +--- + +## Pricing Psychology + +- **Charm Pricing**: $99 feels much cheaper than $100 (left-digit effect) +- **Rounded Prices**: Use for premium products ($500/month signals quality) +- **Rule of 100**: % off under $100 ("20% off"), $ off over $100 ("$50 off") +- **Price Relativity**: Three tiers where the middle is your target +- **Mental Accounting**: "$1/day" feels cheaper than "$30/month" + +--- + +## Growth & Scaling Models + +### Flywheel Effect +Content → traffic → leads → customers → case studies → more content. Each element powers the next. + +### Network Effects +A product becomes more valuable as more people use it. Design features that improve with more users. + +### Switching Costs +Increase ethically: integrations, data accumulation, workflow customization, team adoption. + +### Compounding +Small, consistent gains accumulate into large results. Content, SEO, and brand building compound over time. + +### Survivorship Bias +Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see. + +--- + +## Quick Reference + +| Challenge | Models to Apply | +|-----------|-----------------| +| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction | +| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion | +| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect | +| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect | +| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias | +| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding | +| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory | +| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency | + +--- + +## Related Skills + +- **growth**: Apply psychology to CRO, signup, onboarding, paywalls +- **copywriting**: Write copy using psychological principles +- **pricing-strategy**: Pricing psychology in practice diff --git a/meta-ads/SKILL.md b/meta-ads/SKILL.md index f2bb706..638e704 100644 --- a/meta-ads/SKILL.md +++ b/meta-ads/SKILL.md @@ -12,7 +12,7 @@ Daily 4am routine: audit running ads via Meta Marketing API, kill underperformer ## API Credentials ```bash -TOKEN=$META_ACCESS_TOKEN # Meta Marketing API token +TOKEN=$FACEBOOK_ACCESS_TOKEN # Meta Marketing API token ACCOUNT="$BLOOM_AD_ACCOUNT_ID" # Bloom ad account (act_...) API="https://graph.facebook.com/v22.0" PAGE_ID="$BLOOM_PAGE_ID" # Facebook Page ID @@ -342,7 +342,7 @@ For iOS app campaigns, use Apple Custom Product Pages (CPPs) as the ad destinati ## Common Mistakes -1. **Token not set** — always use `$META_ACCESS_TOKEN` from env. Never hardcode. +1. **Token not set** — always use `$FACEBOOK_ACCESS_TOKEN` from env. Never hardcode. 2. **Wrong budget units** — daily_budget is in cents. $5/day = 500, $6/day = 600. 3. **Repeating a hook/format/concept combo** — always audit exclusion list first. 4. **Forgetting Android ad set** — each creative should get two ads (iOS + Android ad sets). diff --git a/paid-ads/SKILL.md b/paid-ads/SKILL.md new file mode 100644 index 0000000..a111599 --- /dev/null +++ b/paid-ads/SKILL.md @@ -0,0 +1,199 @@ +--- +name: paid-ads +description: "When the user wants help with paid advertising campaigns on Google Ads, Meta, LinkedIn, Twitter/X, or other platforms. Use when someone mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'Google Ads,' 'Facebook ads,' 'ad budget,' or 'should I run ads.' For Meta API operations, see meta-ads. For Google Ads API, see google-ads." +metadata: + version: 1.0.0 +--- + +# Paid Ads + +Expert performance marketer. Create, optimize, and scale paid advertising campaigns for efficient customer acquisition. + +## Before Starting + +Read `.agents/product-marketing-context.md` if it exists — it contains product name, audience, and brand voice. + +Gather this context (ask if not provided): + +### 1. Campaign Goals +- Primary objective? (Awareness, traffic, leads, sales, app installs) +- Target CPA or ROAS? +- Monthly/weekly budget? + +### 2. Product & Offer +- What are you promoting? +- Landing page URL? + +### 3. Audience +- Ideal customer? +- What are they searching for or interested in? +- Existing customer data for lookalikes? + +### 4. Current State +- Previous ad experience? What worked? +- Pixel/conversion data? + +--- + +## Platform Selection Guide + +| Platform | Best For | Use When | +|----------|----------|----------| +| **Google Ads** | High-intent search traffic | People actively search for your solution | +| **Meta** | Demand generation, visual products | Creating demand, strong creative assets | +| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters | +| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X | +| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity | + +--- + +## Campaign Structure + +``` +Account +├── Campaign 1: [Objective] - [Audience/Product] +│ ├── Ad Set 1: [Targeting variation] +│ │ ├── Ad 1-3: [Creative variations] +│ └── Ad Set 2: [Targeting variation] +└── Campaign 2... +``` + +### Naming Convention +``` +[Platform]_[Objective]_[Audience]_[Offer]_[Date] +META_Conv_Lookalike-Customers_FreeTrial_2024Q1 +``` + +### Budget Allocation + +**Testing phase (first 2-4 weeks):** 70% proven/safe, 30% testing new audiences/creative. + +**Scaling phase:** Consolidate into winners. Increase budgets 20-30% at a time. Wait 3-5 days between increases. + +--- + +## Ad Copy Frameworks + +**Problem-Agitate-Solve (PAS):** [Problem] → [Agitate the pain] → [Introduce solution] → [CTA] + +**Before-After-Bridge (BAB):** [Current painful state] → [Desired future state] → [Your product as bridge] + +**Social Proof Lead:** [Impressive stat or testimonial] → [What you do] → [CTA] + +--- + +## Audience Targeting + +| Platform | Key Targeting | Best Signals | +|----------|---------------|--------------| +| Google | Keywords, search intent | What they're searching | +| Meta | Interests, behaviors, lookalikes | Engagement patterns | +| LinkedIn | Job titles, companies, industries | Professional identity | + +- **Lookalikes**: Base on best customers (by LTV), not all customers +- **Retargeting**: Segment by funnel stage +- **Exclusions**: Exclude existing customers and recent converters + +--- + +## Creative Best Practices + +### Image Ads +- Clear product screenshots, before/after comparisons +- Stats and numbers as focal point +- Human faces (real, not stock) +- Bold readable text overlay (under 20%) + +### Video Ads (15-30 sec) +1. Hook (0-3 sec): Pattern interrupt or bold statement +2. Problem (3-8 sec): Relatable pain point +3. Solution (8-20 sec): Show product/benefit +4. CTA (20-30 sec): Clear next step + +Captions always (85% watch without sound). Native feel outperforms polished. + +### Testing Hierarchy +1. Concept/angle (biggest impact) +2. Hook/headline +3. Visual style +4. Body copy +5. CTA + +--- + +## Campaign Optimization + +**If CPA is too high:** Check landing page, tighten targeting, test new creative, improve quality score, adjust bid strategy. + +**If CTR is low:** New hooks/angles, refine targeting, refresh creative. + +**If CPM is high:** Expand targeting, try different placements, improve creative fit. + +### Bid Strategy Progression +1. Start with manual or cost caps +2. Gather 50+ conversions +3. Switch to automated with targets +4. Monitor and adjust + +--- + +## Retargeting + +| Funnel Stage | Audience | Message | +|--------------|----------|---------| +| Top | Blog readers, video viewers | Educational, social proof | +| Middle | Pricing/feature visitors | Case studies, demos | +| Bottom | Cart abandoners, trial users | Urgency, objection handling | + +### Windows +- Hot (cart/trial): 1-7 days, higher frequency OK +- Warm (key pages): 7-30 days, 3-5x/week +- Cold (any visit): 30-90 days, 1-2x/week + +--- + +## Reporting + +### Weekly Review +- Spend vs. budget pacing +- CPA/ROAS vs. targets +- Top/bottom performing ads +- Frequency check (fatigue risk) +- Landing page conversion rate + +### Attribution +- Platform attribution is inflated +- Use UTM parameters consistently +- Look at blended CAC, not just platform CPA + +--- + +## Pre-Launch Checklist + +- [ ] Conversion tracking tested with real conversion +- [ ] Landing page loads fast (<3 sec) and is mobile-friendly +- [ ] UTM parameters working +- [ ] Budget set correctly +- [ ] Targeting matches intended audience + +--- + +## Common Mistakes + +- Launching without conversion tracking +- Too many campaigns (fragmenting budget) +- Not giving algorithms enough learning time +- Only one ad per ad set +- Not refreshing creative (fatigue) +- Mismatch between ad and landing page +- Spreading budget too thin + +--- + +## Related Skills + +- **meta-ads**: For Meta Marketing API operations +- **google-ads**: For Google Ads API operations +- **copywriting**: For landing page and ad copy +- **growth**: For post-click conversion optimization +- **marketing-psychology**: For ad psychology principles diff --git a/pricing-strategy/SKILL.md b/pricing-strategy/SKILL.md new file mode 100644 index 0000000..617b779 --- /dev/null +++ b/pricing-strategy/SKILL.md @@ -0,0 +1,161 @@ +--- +name: pricing-strategy +description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Use when someone mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'value metric,' 'willingness to pay,' 'how much should I charge,' 'annual vs monthly,' or 'should I offer a free plan.'" +metadata: + version: 1.0.0 +--- + +# Pricing Strategy + +Expert in SaaS pricing and monetization strategy. Design pricing that captures value, drives growth, and aligns with customer willingness to pay. + +## Before Starting + +Read `.agents/product-marketing-context.md` if it exists — it contains product name, audience, and positioning context. + +Gather this context (ask if not provided): + +### 1. Business Context +- What type of product? (SaaS, marketplace, e-commerce, service) +- Current pricing (if any)? +- Target market? (SMB, mid-market, enterprise) +- Go-to-market motion? (self-serve, sales-led, hybrid) + +### 2. Value & Competition +- Primary value delivered? +- What alternatives do customers consider? +- How do competitors price? + +### 3. Current Performance +- Conversion rate, ARPU, churn rate? +- Customer feedback on pricing? + +### 4. Goals +- Optimizing for growth, revenue, or profitability? + +--- + +## Pricing Fundamentals + +### The Three Pricing Axes + +1. **Packaging**: What's included at each tier? +2. **Pricing Metric**: What do you charge for? (per user, usage, flat) +3. **Price Point**: The actual dollar amounts + +### Value-Based Pricing + +- **Customer's perceived value**: The ceiling +- **Your price**: Between alternatives and perceived value +- **Next best alternative**: The floor +- **Your cost to serve**: Only a baseline, not the basis + +--- + +## Value Metrics + +The value metric is what you charge for. It should scale with the value customers receive. + +**Good value metrics:** Align price with value, easy to understand, scale with growth, hard to game. + +| Metric | Best For | Example | +|--------|----------|---------| +| Per user/seat | Collaboration tools | Slack, Notion | +| Per usage | Variable consumption | AWS, Twilio | +| Per feature | Modular products | HubSpot add-ons | +| Per contact/record | CRM, email tools | Mailchimp | +| Per transaction | Payments, marketplaces | Stripe | +| Flat fee | Simple products | Basecamp | + +**Test:** "As a customer uses more of [metric], do they get more value?" If yes, it's a good value metric. + +--- + +## Good-Better-Best Framework + +- **Good** (Entry): Core features, limited usage, low price +- **Better** (Recommended): Full features, reasonable limits, anchor price +- **Best** (Premium): Everything, advanced features, 2-3x Better price + +### Tier Differentiation + +- **Feature gating**: Basic vs. advanced features +- **Usage limits**: Same features, different limits +- **Support level**: Email → Priority → Dedicated +- **Access**: API, SSO, custom branding + +--- + +## Pricing Research + +### Van Westendorp Method + +Four questions that identify acceptable price range: +1. At what price is it too expensive? (wouldn't consider) +2. At what price is it too cheap? (question quality) +3. At what price is it expensive but you'd consider it? +4. At what price is it a bargain? + +Analyze intersections to find optimal pricing zone. + +### MaxDiff Analysis + +Identifies which features customers value most. Show sets of features, ask most/least important. Results inform tier packaging. + +--- + +## When to Raise Prices + +### Signs It's Time + +**Market signals:** Competitors raised prices, prospects don't flinch, "it's so cheap!" feedback. + +**Business signals:** Very high conversion (>40%), very low churn (<3%), strong unit economics. + +**Product signals:** Significant value added since last pricing. + +### Price Increase Strategies + +1. **Grandfather existing**: New price for new customers only +2. **Delayed increase**: Announce 3-6 months out +3. **Tied to value**: Raise price but add features +4. **Plan restructure**: Change plans entirely + +--- + +## Pricing Page Best Practices + +- Clear tier comparison table, recommended tier highlighted +- Monthly/annual toggle, annual discount callout (17-20%) +- FAQ section, money-back guarantee, customer logos +- **Anchoring:** Show higher-priced option first +- **Decoy effect:** Middle tier should be best value +- **Charm pricing:** $49 vs. $50 (for value-focused) +- **Round pricing:** $50 vs. $49 (for premium) + +--- + +## Pricing Checklist + +### Before Setting Prices +- [ ] Defined target customer personas +- [ ] Researched competitor pricing +- [ ] Identified your value metric +- [ ] Conducted willingness-to-pay research +- [ ] Mapped features to tiers + +### Pricing Structure +- [ ] Chosen number of tiers +- [ ] Differentiated tiers clearly +- [ ] Set price points based on research +- [ ] Created annual discount strategy +- [ ] Planned enterprise/custom tier + +--- + +## Related Skills + +- **churn-prevention**: Cancel flows, save offers, revenue churn +- **growth**: Pricing page optimization, paywall CRO +- **copywriting**: Pricing page copy +- **marketing-psychology**: Pricing psychology principles diff --git a/product-marketing-context/SKILL.md b/product-marketing-context/SKILL.md new file mode 100644 index 0000000..9bd90b7 --- /dev/null +++ b/product-marketing-context/SKILL.md @@ -0,0 +1,173 @@ +--- +name: product-marketing-context +description: "When the user wants to create or update their product marketing context document. Use at the start of any new project before using other marketing skills. Creates a context file that all other skills reference for product, audience, and positioning info." +metadata: + version: 1.0.0 +--- + +# Product Marketing Context + +Help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves. + +The document is stored at `.agents/product-marketing-context.md`. + +## Workflow + +### Step 1: Check for Existing Context + +Check if `.agents/product-marketing-context.md` exists. + +**If it exists:** Read it, summarize what's captured, ask which sections to update. + +**If it doesn't exist, offer two options:** + +1. **Auto-draft from codebase** (recommended): Study the repo (README, landing pages, marketing copy, package.json) and draft a V1. User reviews, corrects, fills gaps. + +2. **Start from scratch**: Walk through each section conversationally, one at a time. + +### Step 2: Gather Information + +Push for verbatim customer language. Exact phrases are more valuable than polished descriptions because they reflect how customers actually think. + +--- + +## Sections to Capture + +### 1. Product Overview +- One-line description +- What it does (2-3 sentences) +- Product category (what "shelf" you sit on) +- Product type (SaaS, marketplace, e-commerce, service) +- Business model and pricing + +### 2. Target Audience +- Target company type (industry, size, stage) +- Target decision-makers (roles, departments) +- Primary use case +- Jobs to be done (2-3 things customers "hire" you for) +- Specific use cases or scenarios + +### 3. Personas (B2B only) +For each stakeholder: User, Champion, Decision Maker, Financial Buyer, Technical Influencer. What each cares about, their challenge, the value you promise. + +### 4. Problems & Pain Points +- Core challenge before finding you +- Why current solutions fall short +- What it costs them (time, money, opportunities) +- Emotional tension (stress, fear, doubt) + +### 5. Competitive Landscape +- **Direct competitors**: Same solution, same problem +- **Secondary competitors**: Different solution, same problem +- **Indirect competitors**: Conflicting approach +- How each falls short + +### 6. Differentiation +- Key differentiators +- How you solve it differently +- Why that's better +- Why customers choose you over alternatives + +### 7. Objections & Anti-Personas +- Top 3 objections and how to address them +- Who is NOT a good fit + +### 8. Switching Dynamics (JTBD Four Forces) +- **Push**: Frustrations with current solution +- **Pull**: What attracts them to you +- **Habit**: What keeps them stuck +- **Anxiety**: What worries them about switching + +### 9. Customer Language +- How customers describe the problem (verbatim) +- How they describe your solution (verbatim) +- Words/phrases to use and avoid +- Glossary of product-specific terms + +### 10. Brand Voice +- Tone, communication style, brand personality (3-5 adjectives) + +### 11. Proof Points +- Key metrics or results to cite +- Notable customers/logos +- Testimonial snippets + +### 12. Goals +- Primary business goal +- Key conversion action +- Current metrics + +--- + +## Document Template + +```markdown +# Product Marketing Context + +*Last updated: [date]* + +## Product Overview +**One-liner:** +**What it does:** +**Product category:** +**Product type:** +**Business model:** + +## Target Audience +**Target companies:** +**Decision-makers:** +**Primary use case:** +**Jobs to be done:** + +## Problems & Pain Points +**Core problem:** +**Why alternatives fall short:** +**What it costs them:** +**Emotional tension:** + +## Competitive Landscape +**Direct:** [Competitor] — falls short because... +**Secondary:** [Approach] — falls short because... + +## Differentiation +**Key differentiators:** +**Why customers choose us:** + +## Objections +| Objection | Response | +|-----------|----------| + +## Customer Language +**How they describe the problem:** "[verbatim]" +**How they describe us:** "[verbatim]" +**Words to use:** +**Words to avoid:** + +## Brand Voice +**Tone:** +**Style:** +**Personality:** + +## Proof Points +**Metrics:** +**Customers:** + +## Goals +**Business goal:** +**Conversion action:** +``` + +--- + +## Step 3: Confirm and Save + +Show the completed document, ask for adjustments, save to `.agents/product-marketing-context.md`. Other marketing skills will reference this context automatically. + +--- + +## Related Skills + +- **competitive-analysis**: For deeper competitive research +- **brand-identity**: For visual and verbal brand identity +- **positioning-angles**: For positioning framework development +- **copywriting**: For writing copy using this context diff --git a/referral-program/SKILL.md b/referral-program/SKILL.md new file mode 100644 index 0000000..521fef6 --- /dev/null +++ b/referral-program/SKILL.md @@ -0,0 +1,131 @@ +--- +name: referral-program +description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Use when someone mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' or 'partner program.'" +metadata: + version: 1.0.0 +--- + +# Referral & Affiliate Programs + +Expert in viral growth and referral marketing. Design and optimize programs that turn customers into growth engines. + +## Before Starting + +Gather this context (ask if not provided): + +1. **Program Type**: Customer referral, affiliate, or both? B2B or B2C? +2. **Economics**: Average customer LTV? Current CAC from other channels? +3. **Current State**: Existing program? Current referral rate? +4. **Product Fit**: Is the product naturally shareable? Network effects? + +--- + +## Referral vs. Affiliate + +### Customer Referral Programs +Best for: existing customers recommending to their network, natural word-of-mouth, lower-ticket self-serve products. Higher trust, lower volume. + +### Affiliate Programs +Best for: reaching audiences you don't have access to, content creators, influencers, bloggers. Higher volume, variable trust. + +--- + +## Referral Program Design + +### The Referral Loop + +``` +Trigger Moment → Share Action → Convert Referred → Reward → (Loop) +``` + +### Step 1: Identify Trigger Moments + +High-intent moments: right after first "aha" moment, after achieving a milestone, after exceptional support, after renewing or upgrading. + +### Step 2: Design Share Mechanism + +Ranked by effectiveness: +1. In-product sharing (highest conversion) +2. Personalized link +3. Email invitation +4. Social sharing +5. Referral code (works offline) + +### Step 3: Choose Incentive Structure + +- **Single-sided** (referrer only): Simpler, works for high-value products +- **Double-sided** (both parties): Higher conversion, win-win framing +- **Tiered**: Gamifies process, increases engagement + +--- + +## Program Optimization + +### If Few Customers Are Referring +- Ask at better moments +- Simplify sharing process +- Test different incentive types +- Make referral prominent in product + +### If Referrals Aren't Converting +- Improve landing experience for referred users +- Strengthen incentive for new users +- Ensure referrer's endorsement is visible + +### Common Problems & Fixes + +| Problem | Fix | +|---------|-----| +| Low awareness | Add prominent in-app prompts | +| Low share rate | Simplify to one click | +| Low conversion | Optimize referred user experience | +| Fraud/abuse | Add verification, limits | +| One-time referrers | Add tiered/gamified rewards | + +--- + +## Measuring Success + +### Key Metrics +- Active referrers (referred in last 30 days) +- Referral conversion rate +- % new customers from referrals +- CAC via referral vs. other channels +- LTV of referred customers + +### Typical Results +- Referred customers have 16-25% higher LTV +- Referred customers have 18-37% lower churn +- Referred customers refer others at 2-3x rate + +--- + +## Launch Checklist + +### Before Launch +- [ ] Define program goals and success metrics +- [ ] Design incentive structure +- [ ] Build or configure referral tool +- [ ] Create referral landing page +- [ ] Set up tracking and attribution +- [ ] Define fraud prevention rules + +### Launch +- [ ] Announce to existing customers +- [ ] Add in-app referral prompts +- [ ] Update website with program details + +### Post-Launch (First 30 Days) +- [ ] Review conversion funnel +- [ ] Identify top referrers +- [ ] Fix friction points +- [ ] Send reminder emails to non-referrers + +--- + +## Related Skills + +- **launch-strategy**: For launching the referral program effectively +- **email-sequence**: For referral nurture campaigns +- **marketing-psychology**: For understanding referral motivation +- **growth**: For referral program design patterns diff --git a/seo-research/SKILL.md b/seo-research/SKILL.md index 64a23f7..c3bfc94 100644 --- a/seo-research/SKILL.md +++ b/seo-research/SKILL.md @@ -24,6 +24,7 @@ Unified SEO skill covering keyword research, AI search optimization, programmati | E-E-A-T detailed criteria | `references/eeat-framework.md` | | Content quality thresholds | `references/quality-gates.md` | | Core Web Vitals thresholds | `references/cwv-thresholds.md` | +| Site architecture, page hierarchy, URL structure, internal linking | `references/site-architecture.md` | | Bloom keyword seeds | `references/keyword-seeds.md` | --- @@ -31,7 +32,7 @@ Unified SEO skill covering keyword research, AI search optimization, programmati ## Pipeline Position ``` -THIS SKILL (what to write about) → hooks → outline-generator → article-writer → image-generator → substack-draft → distribution +THIS SKILL (what to write about) → headlines → outline-generator → article-writer → image-generator → substack-draft → distribution ``` --- @@ -317,6 +318,7 @@ For full audit checklist, read `references/seo-technical.md`. Critical items: | `references/eeat-framework.md` | Detailed E-E-A-T criteria | | `references/quality-gates.md` | Content quality thresholds | | `references/cwv-thresholds.md` | Core Web Vitals thresholds | +| `references/site-architecture.md` | Site architecture: page hierarchy, URL patterns, navigation, internal linking | | `references/keyword-seeds.md` | Bloom keyword seed list | --- @@ -324,6 +326,6 @@ For full audit checklist, read `references/seo-technical.md`. Critical items: ## Related Skills - **trend-scout** — viral content signals (complements SEO) -- **hooks** — turns keyword research into titles +- **headlines** — turns keyword research into titles - **content-calendar** — tracks research → written → published - **competitive-analysis** — competitor comparison pages (see references/seo-competitor-pages.md) diff --git a/seo-research/references/ai-seo.md b/seo-research/references/ai-seo.md index ebd806f..f614f62 100644 --- a/seo-research/references/ai-seo.md +++ b/seo-research/references/ai-seo.md @@ -11,7 +11,7 @@ You are an expert in AI search optimization — the practice of making content d ## Before Starting -Read `product-marketing-context.md` in the workspace root if it exists. Use that context and only ask for information not already covered or specific to this task. +Read `.agents/product-marketing-context.md` if it exists. Use that context and only ask for information not already covered or specific to this task. Gather this context (ask if not provided): diff --git a/seo-research/references/seo-technical.md b/seo-research/references/seo-technical.md index 099a74d..87eb479 100644 --- a/seo-research/references/seo-technical.md +++ b/seo-research/references/seo-technical.md @@ -146,3 +146,60 @@ Google updated its JavaScript SEO documentation in December 2025 with critical c ### High Priority (fix within 1 week) ### Medium Priority (fix within 1 month) ### Low Priority (backlog) + +--- + +## Full SEO Audit Output Format + +Structure recommendations as: + +**Executive Summary:** Overall health assessment, top 3-5 priority issues, quick wins identified. + +**Technical SEO Findings / On-Page SEO Findings / Content Findings:** For each issue: Issue → Impact (High/Medium/Low) → Evidence → Fix → Priority. + +**Prioritized Action Plan:** +1. Critical fixes (blocking indexation/ranking) +2. High-impact improvements +3. Quick wins (easy, immediate benefit) +4. Long-term recommendations + +### Schema Markup Detection Limitation + +`web_fetch` and `curl` cannot reliably detect structured data / schema markup. Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript, which won't appear in static HTML or `web_fetch` output. + +**To accurately check for schema markup:** +1. Browser tool: render the page and run `document.querySelectorAll('script[type="application/ld+json"]')` +2. Google Rich Results Test: https://search.google.com/test/rich-results +3. Screaming Frog export (renders JavaScript) + +--- + +## Common Issues by Site Type + +### SaaS/Product Sites +- Product pages lack content depth +- Blog not integrated with product pages +- Missing comparison/alternative pages +- Feature pages thin on content +- No glossary/educational content + +### E-commerce +- Thin category pages +- Duplicate product descriptions +- Missing product schema +- Faceted navigation creating duplicates +- Out-of-stock pages mishandled + +### Content/Blog Sites +- Outdated content not refreshed +- Keyword cannibalization +- No topical clustering +- Poor internal linking +- Missing author pages + +### Local Business +- Inconsistent NAP +- Missing local schema +- No Google Business Profile optimization +- Missing location pages +- No local content diff --git a/seo-research/references/site-architecture.md b/seo-research/references/site-architecture.md new file mode 100644 index 0000000..97e6ba4 --- /dev/null +++ b/seo-research/references/site-architecture.md @@ -0,0 +1,163 @@ +# Site Architecture + +Information architecture guide: page hierarchy, navigation design, URL patterns, and internal linking for SEO. + +--- + +## Site Types and Starting Points + +| Site Type | Typical Depth | Key Sections | URL Pattern | +|-----------|--------------|--------------|-------------| +| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | `/features/name`, `/blog/slug` | +| Content/blog | 2-3 levels | Home, Blog, Categories, About | `/blog/slug`, `/category/slug` | +| E-commerce | 3-4 levels | Home, Categories, Products, Cart | `/category/subcategory/product` | +| Documentation | 3-4 levels | Home, Guides, API Reference | `/docs/section/page` | +| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | `/product/feature`, `/blog/slug` | +| Small business | 1-2 levels | Home, Services, About, Contact | `/services/name` | + +--- + +## Page Hierarchy Design + +### The 3-Click Rule + +Users should reach any important page within 3 clicks from the homepage. If critical pages are buried 4+ levels deep, something is wrong. + +### Flat vs Deep + +| Approach | Best For | Tradeoff | +|----------|----------|----------| +| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale | +| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability | +| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content | + +**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy. + +### Hierarchy Levels + +| Level | What It Is | Example | +|-------|-----------|---------| +| L0 | Homepage | `/` | +| L1 | Primary sections | `/features`, `/blog`, `/pricing` | +| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` | +| L3+ | Detail pages | `/docs/api/authentication` | + +--- + +## URL Structure + +### Design Principles + +1. **Readable by humans**: `/features/analytics` not `/f/a123` +2. **Hyphens, not underscores**: `/blog/seo-guide` not `/blog/seo_guide` +3. **Reflect the hierarchy**: URL path should match site structure +4. **Consistent trailing slash policy**: pick one and enforce it +5. **Lowercase always**: `/About` should redirect to `/about` +6. **Short but descriptive**: `/blog/landing-page-conversions` over `/blog/how-to-improve-landing-page-conversion-rates` + +### URL Patterns by Page Type + +| Page Type | Pattern | Example | +|-----------|---------|---------| +| Homepage | `/` | `example.com` | +| Feature page | `/features/{name}` | `/features/analytics` | +| Pricing | `/pricing` | `/pricing` | +| Blog post | `/blog/{slug}` | `/blog/seo-guide` | +| Blog category | `/blog/category/{slug}` | `/blog/category/seo` | +| Case study | `/customers/{slug}` | `/customers/acme-corp` | +| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` | +| Legal | `/{page}` | `/privacy`, `/terms` | +| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` | +| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` | +| Integration | `/integrations/{name}` | `/integrations/slack` | + +### Common Mistakes + +- **Dates in blog URLs**: `/blog/2024/01/15/post-title` adds no value. Use `/blog/post-title`. +- **Over-nesting**: `/products/category/subcategory/item/detail` is too deep. Flatten where possible. +- **Changing URLs without redirects**: Every old URL needs a 301 redirect. Without them, you lose backlink equity. +- **IDs in URLs**: `/product/12345` is not human-readable. Use slugs. +- **Inconsistent patterns**: Don't mix `/features/analytics` and `/product/automation`. Pick one parent. + +--- + +## Navigation Design + +### Navigation Types + +| Nav Type | Purpose | Placement | +|----------|---------|-----------| +| Header nav | Primary navigation, always visible | Top of every page | +| Dropdown menus | Organize sub-pages under parent | Expands from header items | +| Footer nav | Secondary links, legal, sitemap | Bottom of every page | +| Sidebar nav | Section navigation (docs, blog) | Left side within a section | +| Breadcrumbs | Show current location in hierarchy | Below header, above content | +| Contextual links | Related content, next steps | Within page content | + +### Header Navigation Rules + +- **4-7 items max** in the primary nav +- **CTA button** goes rightmost (e.g., "Start Free Trial") +- **Logo** links to homepage (left side) +- **Order by priority**: most important/visited pages first + +### Footer Organization + +Group footer links into columns: +- **Product**: Features, Pricing, Integrations, Changelog +- **Resources**: Blog, Case Studies, Templates, Docs +- **Company**: About, Careers, Contact, Press +- **Legal**: Privacy, Terms, Security + +### Breadcrumbs + +``` +Home > Features > Analytics +Home > Blog > SEO Category > Post Title +``` + +Breadcrumbs should mirror the URL hierarchy. Every segment clickable except the current page. + +--- + +## Internal Linking Strategy + +### Link Types + +| Type | Purpose | Example | +|------|---------|---------| +| Navigational | Move between sections | Header, footer, sidebar links | +| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" | +| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page | +| Cross-section | Connect related pages across sections | Feature page linking to related case study | + +### Internal Linking Rules + +1. **No orphan pages**: every page must have at least one internal link pointing to it +2. **Descriptive anchor text**: "our analytics features" not "click here" +3. **5-10 internal links per 1000 words** of content (approximate guideline) +4. **Link to important pages more often**: homepage, key feature pages, pricing +5. **Use breadcrumbs**: free internal links on every page +6. **Related content sections**: "Related Posts" at page bottom + +### Hub-and-Spoke Model + +``` +Hub: /blog/seo-guide (comprehensive overview) +├── Spoke: /blog/keyword-research (links back to hub) +├── Spoke: /blog/on-page-seo (links back to hub) +├── Spoke: /blog/technical-seo (links back to hub) +└── Spoke: /blog/link-building (links back to hub) +``` + +Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant. + +### Link Audit Checklist + +- [ ] Every page has at least one inbound internal link +- [ ] No broken internal links (404s) +- [ ] Anchor text is descriptive +- [ ] Important pages have the most inbound internal links +- [ ] Breadcrumbs implemented on all pages +- [ ] Related content links exist on blog posts +- [ ] Cross-section links connect features to case studies, blog to product pages From 2ce513977524e3a353cfa8a96438b09563ebd09a Mon Sep 17 00:00:00 2001 From: testuser Date: Mon, 30 Mar 2026 09:20:41 -0400 Subject: [PATCH 02/18] fix: correct hooks reference, update README description, remove dead reference file entries (#51) --- README.md | 2 +- content-strategy/SKILL.md | 5 +---- seo-research/SKILL.md | 4 ++-- 3 files changed, 4 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 35e1acf..ac48af8 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ cp -r ~/Projects/erics-skills/skills/copywriting ~/.clawdbot/skills/ | Skill | Description | |-------|-------------| -| [copywriting](copywriting/SKILL.md) | write ad copy: App Store listings, Google Ads, landing pages, TikTok/Meta scripts, push, email. | +| [copywriting](copywriting/SKILL.md) | Page copy frameworks + direct response for any platform (ads, App Store, landing pages, scripts). | | [article-writer](article-writer/SKILL.md) | write article drafts from approved outlines with SEO and brand voice. | | [content-atomizer](content-atomizer/SKILL.md) | repurpose long-form content into platform-native pieces for 8+ channels. | | [editor-in-chief](editor-in-chief/SKILL.md) | autonomous editing orchestrator: diagnose, fix, and iterate drafts to quality. | diff --git a/content-strategy/SKILL.md b/content-strategy/SKILL.md index 532bbb5..d7f7cfe 100644 --- a/content-strategy/SKILL.md +++ b/content-strategy/SKILL.md @@ -520,10 +520,7 @@ Source: @DTC_Quizbuilder thread (https://x.com/DTC_Quizbuilder/status/2010379560 | `references/lead-magnets.md` | Lead magnet types, buyer stage matching, gating strategy, distribution, benchmarks | | `references/marketing-ideas.md` | 139 SaaS marketing ideas catalog organized by category, stage, and budget | | `references/blog-seo-planning.md` | Searchable vs shareable, content pillars, topic clusters, buyer stage keywords, ideation sources | -| `references/6-elements-framework.md` | Content creation framework | -| `references/copywriting-formulas.md` | Copywriting formulas for social content | -| `references/creative-research-methods.md` | How to research what's working | -| `references/ad-formats-library.md` | Ad format reference library | + --- diff --git a/seo-research/SKILL.md b/seo-research/SKILL.md index c3bfc94..d58e5bc 100644 --- a/seo-research/SKILL.md +++ b/seo-research/SKILL.md @@ -32,7 +32,7 @@ Unified SEO skill covering keyword research, AI search optimization, programmati ## Pipeline Position ``` -THIS SKILL (what to write about) → headlines → outline-generator → article-writer → image-generator → substack-draft → distribution +THIS SKILL (what to write about) → hooks → outline-generator → article-writer → image-generator → substack-draft → distribution ``` --- @@ -326,6 +326,6 @@ For full audit checklist, read `references/seo-technical.md`. Critical items: ## Related Skills - **trend-scout** — viral content signals (complements SEO) -- **headlines** — turns keyword research into titles +- **hooks** — turns keyword research into titles - **content-calendar** — tracks research → written → published - **competitive-analysis** — competitor comparison pages (see references/seo-competitor-pages.md) From 40ad868c98edddaf3bade78558445a22029f331e Mon Sep 17 00:00:00 2001 From: testuser Date: Mon, 30 Mar 2026 13:08:32 -0400 Subject: [PATCH 03/18] =?UTF-8?q?fix:=20correct=20headlines=E2=86=92hooks?= =?UTF-8?q?=20link,=20remove=20duplicate=20copywriting=20entry=20(#51)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index ac48af8..caaa8af 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ cp -r ~/Projects/erics-skills/skills/copywriting ~/.clawdbot/skills/ | [content-atomizer](content-atomizer/SKILL.md) | repurpose long-form content into platform-native pieces for 8+ channels. | | [editor-in-chief](editor-in-chief/SKILL.md) | autonomous editing orchestrator: diagnose, fix, and iterate drafts to quality. | | [evaluate-content](evaluate-content/SKILL.md) | judge content quality: shareability, readability, voice, cuttability, angle. | -| [headlines](headlines/SKILL.md) | generate headlines, titles, and hooks for content. | +| [hooks](hooks/SKILL.md) | generate headlines, titles, and hooks for content. | | [outline-generator](outline-generator/SKILL.md) | generate structured article outlines from approved headlines. | | [substack-draft](substack-draft/SKILL.md) | save finished articles to Substack as drafts. | | [tweet-ideas](tweet-ideas/SKILL.md) | generate standalone tweet ideas about a topic (Aaron Levie playbook). | @@ -127,7 +127,6 @@ cp -r ~/Projects/erics-skills/skills/copywriting ~/.clawdbot/skills/ | Skill | Description | |-------|-------------| -| [copywriting](copywriting/SKILL.md) | Page copy frameworks + direct response for any platform (ads, App Store, landing pages, scripts). | | [marketing-psychology](marketing-psychology/SKILL.md) | Psychological principles, mental models, and behavioral science for marketing. | | [pricing-strategy](pricing-strategy/SKILL.md) | Pricing decisions, tier packaging, value metrics, monetization strategy. | | [launch-strategy](launch-strategy/SKILL.md) | Product launches, feature announcements, Product Hunt, go-to-market. | From cb0195b611d281f01e1a534bd6b2ec126f973024 Mon Sep 17 00:00:00 2001 From: testuser Date: Mon, 30 Mar 2026 16:12:21 -0400 Subject: [PATCH 04/18] =?UTF-8?q?fix:=20correct=20skill-integration=20head?= =?UTF-8?q?lines=E2=86=92hooks=20ref,=20fix=20copy=5Fframeworks=E2=86=92co?= =?UTF-8?q?py-frameworks=20filename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- copywriting/references/references.md | 2 +- copywriting/references/skill-integration.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/copywriting/references/references.md b/copywriting/references/references.md index ca88f9f..d515deb 100644 --- a/copywriting/references/references.md +++ b/copywriting/references/references.md @@ -2,6 +2,6 @@ | File | Contents | |------|----------| -| `references/copy_frameworks.md` | 14 proven copywriting frameworks (PAS, AIDA, BAB, FAB, ACCA, STAR, etc.) with detailed structures, selection matrix by platform/goal, and when-to-use guidance | +| `references/copy-frameworks.md` | 14 proven copywriting frameworks (PAS, AIDA, BAB, FAB, ACCA, STAR, etc.) with detailed structures, selection matrix by platform/goal, and when-to-use guidance | | `references/writing_styles.md` | Voice and tone rules from Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, Collier. Contains banned phrases list, AI tell patterns, and how human copy sounds. | | `references/lead-magnet-patterns.md` | Lead magnet post structures, value framing techniques, CTA patterns for social giveaway posts | diff --git a/copywriting/references/skill-integration.md b/copywriting/references/skill-integration.md index fdb9c28..37aff39 100644 --- a/copywriting/references/skill-integration.md +++ b/copywriting/references/skill-integration.md @@ -1,6 +1,6 @@ # Skill Integration -- **Headlines skill** (`headlines/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). +- **Headlines skill** (`hooks/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). - **Google Ads skill** (`google-ads/SKILL.md`): Use for campaign management, performance queries, and pausing underperformers. This skill writes the copy; that skill deploys and measures it. - **Meta Ads skill** (`meta-ads/SKILL.md`): Use for creating/managing Meta ad creatives and measuring performance. From 986a092de09b5dbf13367b33314a92108803e580 Mon Sep 17 00:00:00 2001 From: testuser Date: Mon, 30 Mar 2026 16:41:05 -0400 Subject: [PATCH 05/18] fix: address all review comments on PR #51\n\n- Revert 'headlines' skill references back to 'hooks' across README,\n content-strategy, evaluate-content, copywriting skill-integration\n- Remove 4 dead reference rows from content-strategy/SKILL.md\n (6-elements-framework, copywriting-formulas, creative-research-methods,\n ad-formats-library)\n- Fix broken refs in copywriting/references/7-ugc-script-templates.md\n (remove sora/ and whop-content-rewards references)\n- Fix broken refs in copywriting/references/lead-magnet-patterns.md\n (replace viral-hook-creator with hooks skill)\n- Remove google-ads reference from paid-ads/SKILL.md description\n- Remove google-ads entry from copywriting/references/skill-integration.md\n- Fix filename reference in copywriting/references/references.md\n (writing_styles.md -> writing-styles.md)\n- Rename writing_styles.md to writing-styles.md (kebab-case consistency)\n- Revert META_ACCESS_TOKEN rename in meta-ads/SKILL.md\n (keep as META_ACCESS_TOKEN, not FACEBOOK_ACCESS_TOKEN)\n- Delete orphaned ad-copy/references/ directory\n- Update stale ~/clawd/SOUL.md and ~/clawd/USER.md references to\n .agents/product-marketing-context.md in growth and seo-research --- README.md | 2 +- .../references/1-app-store-descriptions.md | 192 ------ ad-copy/references/2-google-ads.md | 144 ----- ad-copy/references/3-landing-pages.md | 152 ----- .../references/4-tiktok-meta-ad-scripts.md | 231 ------- ad-copy/references/5-push-notifications.md | 76 --- ad-copy/references/6-email-sequences.md | 253 -------- ad-copy/references/7-ugc-script-templates.md | 195 ------ ad-copy/references/a-b-testing-framework.md | 87 --- ad-copy/references/brand-voice-reference.md | 27 - .../copy-anti-patterns-kill-on-sight.md | 66 -- ad-copy/references/copy_frameworks.md | 568 ------------------ .../references/direct-response-principles.md | 116 ---- ad-copy/references/lead-magnet-patterns.md | 276 --------- .../platform-character-limits-reference.md | 74 --- .../process-writing-copy-with-this-skill.md | 13 - .../references/quick-reference-cta-library.md | 18 - ad-copy/references/quiz-funnel-copy.md | 67 --- ...l-world-examples-finance-investing-apps.md | 61 -- ad-copy/references/references.md | 7 - ad-copy/references/skill-integration.md | 7 - .../test-app-store-screenshot-order.md | 12 - ...the-seven-sweeps-copy-editing-framework.md | 19 - content-strategy/SKILL.md | 10 +- .../references/7-ugc-script-templates.md | 4 +- .../references/lead-magnet-patterns.md | 8 +- copywriting/references/references.md | 2 +- copywriting/references/skill-integration.md | 3 +- .../references/writing-styles.md | 0 copywriting/references/writing_styles.md | 233 ------- evaluate-content/SKILL.md | 4 +- growth/references/psychology-models.md | 2 +- meta-ads/SKILL.md | 4 +- paid-ads/SKILL.md | 2 +- seo-research/references/programmatic-seo.md | 2 +- 35 files changed, 19 insertions(+), 2918 deletions(-) delete mode 100644 ad-copy/references/1-app-store-descriptions.md delete mode 100644 ad-copy/references/2-google-ads.md delete mode 100644 ad-copy/references/3-landing-pages.md delete mode 100644 ad-copy/references/4-tiktok-meta-ad-scripts.md delete mode 100644 ad-copy/references/5-push-notifications.md delete mode 100644 ad-copy/references/6-email-sequences.md delete mode 100644 ad-copy/references/7-ugc-script-templates.md delete mode 100644 ad-copy/references/a-b-testing-framework.md delete mode 100644 ad-copy/references/brand-voice-reference.md delete mode 100644 ad-copy/references/copy-anti-patterns-kill-on-sight.md delete mode 100644 ad-copy/references/copy_frameworks.md delete mode 100644 ad-copy/references/direct-response-principles.md delete mode 100644 ad-copy/references/lead-magnet-patterns.md delete mode 100644 ad-copy/references/platform-character-limits-reference.md delete mode 100644 ad-copy/references/process-writing-copy-with-this-skill.md delete mode 100644 ad-copy/references/quick-reference-cta-library.md delete mode 100644 ad-copy/references/quiz-funnel-copy.md delete mode 100644 ad-copy/references/real-world-examples-finance-investing-apps.md delete mode 100644 ad-copy/references/references.md delete mode 100644 ad-copy/references/skill-integration.md delete mode 100644 ad-copy/references/test-app-store-screenshot-order.md delete mode 100644 ad-copy/references/the-seven-sweeps-copy-editing-framework.md rename ad-copy/references/writing_styles.md => copywriting/references/writing-styles.md (100%) delete mode 100644 copywriting/references/writing_styles.md diff --git a/README.md b/README.md index caaa8af..285f0bb 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ cp -r ~/Projects/erics-skills/skills/copywriting ~/.clawdbot/skills/ | [content-atomizer](content-atomizer/SKILL.md) | repurpose long-form content into platform-native pieces for 8+ channels. | | [editor-in-chief](editor-in-chief/SKILL.md) | autonomous editing orchestrator: diagnose, fix, and iterate drafts to quality. | | [evaluate-content](evaluate-content/SKILL.md) | judge content quality: shareability, readability, voice, cuttability, angle. | -| [hooks](hooks/SKILL.md) | generate headlines, titles, and hooks for content. | +| [hooks](hooks/SKILL.md) | generate hooks, titles, and scroll-stopping openers for content. | | [outline-generator](outline-generator/SKILL.md) | generate structured article outlines from approved headlines. | | [substack-draft](substack-draft/SKILL.md) | save finished articles to Substack as drafts. | | [tweet-ideas](tweet-ideas/SKILL.md) | generate standalone tweet ideas about a topic (Aaron Levie playbook). | diff --git a/ad-copy/references/1-app-store-descriptions.md b/ad-copy/references/1-app-store-descriptions.md deleted file mode 100644 index 81f76f9..0000000 --- a/ad-copy/references/1-app-store-descriptions.md +++ /dev/null @@ -1,192 +0,0 @@ -# 1. App Store Descriptions - -App Store copy is the highest-leverage copy you can write. Every ad, every link, every mention ultimately drives to this page. If the listing doesn't convert, everything upstream is wasted. - -### iOS App Store - -#### App Name (30 characters) - -The name is your #1 ranking factor and your #1 brand signal. Use it wisely. - -**Formula**: `[Brand Name]: [Core Value Prop]` or `[Brand Name] - [Key Benefit]` - -``` -✅ Bloom: Stock Research & AI (28 chars) -✅ Bloom - AI Investing Research (30 chars) -✅ Bloom: AI Stock Analysis (25 chars) - -❌ Bloom (wastes keyword space) -❌ Bloom - The Best AI-Powered... (truncated, looks broken) -❌ Bloom Investing Research AI App (keyword stuffing) -``` - -**Finance/investing app examples that convert:** -- `Robinhood: Investing for All` (28 chars) -- `Webull: Investing & Trading` (27 chars) -- `Seeking Alpha: Stock Market` (27 chars) -- `Morningstar: Investing` (22 chars) - -#### Subtitle (30 characters) - -Reinforces the name with a benefit. Not a feature restatement. - -``` -✅ Research Stocks in Seconds (27 chars) ← benefit + speed -✅ Smarter Stock Research (23 chars) ← benefit -✅ AI-Powered Stock Analysis (26 chars) ← method + what - -❌ Trading & Investing App (generic, no benefit) -❌ Best Stock Market App (claim without proof) -❌ For Investors & Traders (audience, not benefit) -``` - -#### Keyword Field (100 characters) - -Comma-separated. No spaces after commas. Don't repeat words from your name or subtitle (Apple already indexes those). - -``` -stocks,investing,portfolio,trading,analyst,ratings,earnings,research, -finance,market,AI,screener,alerts,dividends,options -``` - -**Rules:** -- Don't waste characters on your app name or competitor names (against guidelines) -- Singular > plural (Apple matches both) -- No spaces after commas (wastes characters) -- Test different keyword combos monthly using Appfigures/App Annie rank tracking -- Prioritize high-volume, medium-competition keywords - -#### Description (4,000 characters) - -Only the first 3 lines (~90 characters) are visible before "more." These 3 lines are your entire pitch for 80% of viewers. - -**Structure:** - -``` -LINE 1-3 (above the fold — this is everything): -[Benefit-driven hook that makes them tap "more"] - -"Research any stock in 30 seconds. Bloom uses AI to break down analyst -ratings, insider trades, earnings, and catalysts — so you make smarter -investment decisions without spending hours reading filings." - -REST OF DESCRIPTION: - -WHY INVESTORS CHOOSE BLOOM -• AI stock research covering 6,000+ tickers -• Real-time analyst rating changes and price targets -• Insider trading alerts (see what executives are buying) -• Earnings breakdowns with AI-generated summaries -• Smart watchlist with custom alerts - -HOW IT WORKS -1. Search any stock or add it to your watchlist -2. Get an instant AI breakdown: bull case, bear case, key metrics -3. Receive alerts when something changes (analyst upgrade, insider buy, earnings beat) - -WHAT MAKES BLOOM DIFFERENT -Unlike stock screeners that give you raw data, Bloom explains what the data means. Our AI reads 10-K filings, earnings transcripts, and analyst reports — then gives you the insight in plain English. - -"I found a 40% undervalued stock in my first week using Bloom." -— App Store review, ★★★★★ - -WHAT'S INCLUDED FREE -✓ AI research for any stock -✓ Watchlist with alerts -✓ Earnings calendar -✓ Basic analyst ratings - -BLOOM PREMIUM -✓ Unlimited AI research conversations -✓ Real-time insider trading data -✓ Advanced screeners and filters -✓ Priority alerts - -Download Bloom. Research your first stock in 60 seconds. -``` - -**Rules:** -- First 3 lines must stand alone as a complete pitch -- Use line breaks aggressively. Walls of text don't get read. -- Bullet points > paragraphs for features -- One user quote with stars. Specificity > effusiveness. -- End with a CTA. "Download Bloom" not "We hope you enjoy our app!" -- Don't use the description for keyword stuffing. iOS doesn't index it. -- Update quarterly. Test different above-fold hooks. - -#### What's New (4,000 characters) - -Most apps waste this with "bug fixes and performance improvements." That's a missed conversion opportunity. - -``` -✅ GOOD: -NEW: AI earnings analysis -Bloom now breaks down earnings reports in real-time. Get the bull case, bear -case, and key surprises within minutes of the announcement. - -Also in this update: -• Faster stock search (2x improvement) -• New insider trading alerts -• Fixed notification delivery on iOS 18 - -❌ BAD: -Bug fixes and performance improvements. -``` - -**Rules:** -- Lead with the most exciting new feature -- Name the specific benefit, not just the feature name -- Include 2-3 smaller improvements as bullets -- This appears on the update screen. It's a re-engagement opportunity. - -#### Screenshot Text - -Screenshots are your most powerful conversion tool. First 3 are visible in search results. - -**Rules:** -- Screenshot 1 = your best pitch (most people only see this one) -- Text on screenshots should be benefits, not feature names -- Max 5-7 words per screenshot overlay -- Show real app UI, not mockups - -``` -Screenshot 1: "Research Any Stock in 30 Seconds" -Screenshot 2: "AI Reads the Filings. You Get the Insight." -Screenshot 3: "Real-Time Analyst Upgrades & Downgrades" -Screenshot 4: "See What Insiders Are Buying" -Screenshot 5: "Earnings Breakdowns in Plain English" -Screenshot 6: "Smart Alerts. Never Miss a Move." -``` - -**Anti-patterns:** -- ❌ "Powerful AI Technology" (means nothing) -- ❌ "Beautiful Interface" (obvious/subjective) -- ❌ "Feature 1, Feature 2, Feature 3" (list dump) -- ❌ Microscopic text that's unreadable on phone screens - -### Google Play Store - -Google Play's description IS indexed for search. This changes everything. - -#### Short Description (80 characters) - -This is your App Store subtitle equivalent but with nearly 3x the space. Use it. - -``` -✅ AI stock research: analyst ratings, insider trades, earnings. All in one app. (79 chars) -✅ Research any stock in 30 seconds with AI. Free to download. (65 chars) - -❌ The best investing app for stock market research (generic) -❌ Bloom is an AI-powered investing research platform (feature, not benefit) -``` - -#### Full Description (4,000 characters) - -Unlike iOS, Google Play DOES index the description for keyword ranking. Weave in keywords naturally, but don't stuff. Google penalizes keyword stuffing. - -**Structure is the same as iOS** but add keyword variations: -- "stock research" and "stock analysis" and "investing research" -- "analyst ratings" and "analyst upgrades" and "price targets" -- Natural keyword density: 2-3% per target keyword - ---- diff --git a/ad-copy/references/2-google-ads.md b/ad-copy/references/2-google-ads.md deleted file mode 100644 index 92e768d..0000000 --- a/ad-copy/references/2-google-ads.md +++ /dev/null @@ -1,144 +0,0 @@ -# 2. Google Ads - -Every character costs money. Literally. Bad copy = higher CPC, lower quality score, wasted budget. - -### Responsive Search Ads (RSA) - -Google tests combinations of your headlines and descriptions. Give it good ingredients. - -#### Headlines (30 characters each, up to 15) - -Write headlines in tiers: - -**Tier 1: Benefit headlines (write 5)** -``` -Research Stocks in Seconds (26) -AI Stock Research App (21) -Free Stock Analysis Tool (24) -See Why Stocks Move (19) -Never Miss an Upgrade (22) -``` - -**Tier 2: Proof/trust headlines (write 3)** -``` -4.8★ Rating, 2,400+ Reviews (28) -52,000+ Investors Use Bloom (27) -Free Download, No Card Needed (30) -``` - -**Tier 3: CTA headlines (write 3)** -``` -Download Bloom Free (19) -Start Investing Smarter (23) -Try Bloom - It's Free (20) -``` - -**Tier 4: Keyword-match headlines (write 4)** -``` -AI Investing Research (21) -Stock Research Made Simple (26) -Best Stock Analysis App (23) -Analyst Ratings & Alerts (24) -``` - -**Rules:** -- Pin your strongest benefit headline to Position 1 -- Pin your strongest CTA to Position 3 -- Let Google test the rest -- No two headlines should say the same thing differently -- Include the primary keyword in at least 3 headlines -- Use Title Case (Google standard) - -#### Descriptions (90 characters each, up to 4) - -``` -Description 1 (benefit + proof): -"Research any stock in 30 seconds. AI-powered analysis used by 52,000+ investors." (82) - -Description 2 (how it works): -"Get analyst ratings, insider trades, and earnings breakdowns. All in one free app." (83) - -Description 3 (risk reversal): -"Free to download. No credit card. Cancel premium anytime. Start in under a minute." (84) - -Description 4 (differentiator): -"Unlike screeners, Bloom explains what the data means. AI reads filings for you." (81) -``` - -**Rules:** -- Description 1 should work alone (it's shown most often) -- Include a CTA in at least one description -- Include social proof in at least one description -- Don't repeat headline copy in descriptions - -#### Performance Max Asset Groups - -Performance Max needs more creative variation. Supply: - -| Asset Type | Quantity | Bloom Examples | -|-----------|----------|----------------| -| Headlines (30 char) | 5 min | Same RSA headlines | -| Long headlines (90 char) | 5 min | "Research Any Stock in 30 Seconds with AI-Powered Analysis. Download Free." | -| Descriptions (90 char) | 4 min | Same RSA descriptions | -| Business name | 1 | "Bloom" | -| Call to action | 1 | "Download" or "Get offer" | -| Images | 3+ (1200x628, 960x960, 480x600) | App screenshots, results, UI | -| Videos | 1+ (landscape + vertical) | Same as TikTok/Meta scripts | -| Final URL | 1 | App Store / landing page URL | - -#### Display URL Paths (15 characters each) - -``` -getbloom.app/Stock/Research ← tells them what they'll find -getbloom.app/AI/Investing ← keyword reinforcement -getbloom.app/Free/Download ← risk reversal in the URL -``` - -#### Ad Extensions (use all of them) - -**Sitelinks (25 char title + 35 char description × 2):** -``` -Title: "AI Stock Research" -Desc 1: "Search 6,000+ tickers instantly." -Desc 2: "AI reads the filings for you." - -Title: "Real-Time Alerts" -Desc 1: "Analyst upgrades. Insider buys." -Desc 2: "Never miss a move on your stocks." - -Title: "Free to Download" -Desc 1: "No credit card required." -Desc 2: "Research your first stock in 60s." - -Title: "See App Reviews" -Desc 1: "4.8★ average from 2,400+ ratings." -Desc 2: "Investors love Bloom's AI research." -``` - -**Callouts (25 characters):** -``` -Free to Download -AI-Powered Research -6,000+ Stocks Covered -Real-Time Analyst Alerts -No Credit Card Needed -4.8★ App Store Rating -``` - -**Structured Snippets:** -``` -Type: Features -Values: AI Research, Analyst Ratings, Insider Trades, Earnings Analysis, Smart Alerts, Watchlists -``` - -### Google Ads Quality Score Rules - -Quality Score directly affects your CPC. Higher score = lower cost per click. - -1. **Ad relevance**: Headlines must contain the keyword the ad group targets -2. **Landing page experience**: The page must deliver on the ad's promise -3. **Expected CTR**: Specific, benefit-driven copy gets more clicks - -**The #1 mistake:** Writing one ad that targets every keyword. Write ad groups around tight keyword themes. "AI stock research" ads and "analyst rating alerts" ads need different copy. - ---- diff --git a/ad-copy/references/3-landing-pages.md b/ad-copy/references/3-landing-pages.md deleted file mode 100644 index 8c77288..0000000 --- a/ad-copy/references/3-landing-pages.md +++ /dev/null @@ -1,152 +0,0 @@ -# 3. Landing Pages - -A landing page has one job: convert visitors into users. One page, one CTA, one action. - -### Structure (top to bottom) - -#### Hero Section - -``` -HEADLINE (8-12 words): -"Research Any Stock in 30 Seconds" - -SUBHEADLINE (15-25 words): -"Bloom uses AI to break down analyst ratings, insider trades, and earnings. -52,000 investors already use it." - -CTA BUTTON: -"Download Free" (primary) -"See How It Works" (secondary, for non-ready visitors) - -VISUAL: -App screenshot showing real stock analysis (NOT a mockup, NOT an abstract illustration) -``` - -**Hero rules:** -- Headline = biggest benefit, not product name -- Subheadline = how it works + social proof -- CTA above the fold. Always. -- Show the product. People want to see what they're getting. - -#### Problem Section - -``` -HEADER: "Researching Stocks Shouldn't Take Hours" - -You're juggling Yahoo Finance, SEC filings, Reddit threads, and CNBC alerts. -By the time you piece it all together, the move already happened. - -[Visual: cluttered multi-tab browser screenshot vs. clean Bloom UI] -``` - -Name the specific pain. "Investing is hard" is not a problem statement. "You're checking 6 sources to make one decision" is. - -#### Solution Section - -``` -HEADER: "One Screen. Every Insight." - -Bloom reads the filings, tracks the analysts, monitors insider trades, and -summarizes it all in plain English. - -FEATURE BLOCKS (3 max, benefit-first): -1. "30-Second Research" — Search any stock, get the full picture instantly -2. "Real-Time Alerts" — Analyst upgrades, insider buys, earnings surprises -3. "AI That Cites Sources" — Not a black box. See exactly where insights come from. -``` - -**Rules:** -- 3 features max. More than 3 is a feature dump, not a value prop. -- Each feature = benefit headline + one-sentence explanation -- Benefit first, feature second: "Research in 30 seconds" (benefit) using "AI-powered analysis" (feature) - -#### Social Proof Section - -``` -HEADER: "52,000 Investors Already Use Bloom" - -★★★★★ "I found a 40% undervalued stock in my first week." -— @InvestorMike, App Store review - -★★★★★ "Replaced Yahoo Finance, Seeking Alpha, and 3 other apps." -— @SarahK, App Store review - -★★★★★ "The AI actually explains WHY a stock is moving. Not just that it moved." -— @TraderJohn, App Store review - -[App Store badge: 4.8★ from 2,400+ ratings] -[As featured in: TechCrunch, Product Hunt #1] -``` - -**Rules:** -- Real reviews only. Fake testimonials are illegal and detectable. -- Specific results > general praise. "Found a 40% undervalued stock" > "Great app!" -- Include name/handle for credibility -- Show aggregate rating (4.8★) for quick scanning -- 3 testimonials is the sweet spot. More = diminishing returns. - -#### Objection Handling - -Address the top 3-5 reasons someone would NOT convert. Put these below social proof. - -``` -"Is it really free?" -Yes. Download and basic research are completely free. No credit card required. -Premium unlocks unlimited AI conversations and advanced alerts. - -"Is the AI actually good?" -Bloom's AI cites its sources. Every insight links back to the filing, transcript, -or data point it came from. No hallucinated financial advice. - -"I already use [competitor]." -Bloom isn't a replacement for your brokerage. It's a research layer that makes -every platform better. Use Bloom to research, use your broker to trade. - -"Is my data safe?" -Bloom doesn't access your brokerage accounts. Read-only market data. Your -portfolio data stays on your device. -``` - -#### CTA Section (Bottom) - -``` -HEADER: "Research Your First Stock in 60 Seconds" - -[CTA Button: "Download Free"] - -Free. No credit card. Available on iOS and Android. -``` - -Repeat the CTA at the bottom. Many people scroll the entire page before deciding. Give them an easy action at every scroll depth. - -#### Pricing Section (if applicable) - -``` -FREE PREMIUM ($X/month) -✓ AI research (5/day) ✓ Unlimited AI research -✓ Basic watchlist ✓ Advanced screeners -✓ Earnings calendar ✓ Real-time insider data -✓ Market news ✓ Priority alerts - ✓ Full analyst rating history - - [Start Free] [Go Premium] -``` - -**Rules:** -- Free tier should feel generous, not crippled -- Premium should feel like a clear upgrade, not a necessity -- Anchor price against competitors: "Less than one Seeking Alpha subscription" -- If offering a trial: "14-day free trial. Cancel in one tap." - -### Landing Page Anti-Patterns - -- ❌ Multiple CTAs competing for attention (pick ONE primary action) -- ❌ Navigation menu with links away from the page (remove nav on landing pages) -- ❌ Stock photos of smiling people pointing at phones -- ❌ Feature lists with no benefits attached -- ❌ "Learn More" as CTA text (learn more about what? be specific) -- ❌ Walls of text with no visual breaks -- ❌ Pop-ups that appear before the visitor has read anything -- ❌ No social proof anywhere on the page - ---- diff --git a/ad-copy/references/4-tiktok-meta-ad-scripts.md b/ad-copy/references/4-tiktok-meta-ad-scripts.md deleted file mode 100644 index 13f212f..0000000 --- a/ad-copy/references/4-tiktok-meta-ad-scripts.md +++ /dev/null @@ -1,231 +0,0 @@ -# 4. TikTok / Meta Ad Scripts - -Video ads follow a strict rhythm. Every second is earned. - -### The Universal Ad Script Structure - -``` -HOOK (0-3 seconds) — Stop the scroll. Pattern interrupt. -PROBLEM (3-8 seconds) — Name their pain. Be specific. -SOLUTION (8-18 seconds)— Show the product solving the problem. -PROOF (18-23 seconds) — Social proof, results, credibility. -CTA (23-30 seconds) — Tell them exactly what to do. -``` - -Total: 25-30 seconds for conversion ads. Shorter is better. If you can do it in 15 seconds, do it in 15 seconds. - -### Script Templates - -#### Template 1: "I Found the Thing" (Personal Discovery) - -``` -HOOK (0-2s): -[Text overlay: "The app Wall Street doesn't want you to have"] -[Voice]: "I've been using this one app for all my stock research..." - -PROBLEM (2-7s): -"I used to spend HOURS reading analyst reports and SEC filings. -Yahoo Finance, Seeking Alpha, Reddit, earnings transcripts... -by the time I had a thesis, the stock already moved." - -SOLUTION (7-17s): -"Then I found Bloom. You search any stock and it gives you -EVERYTHING: analyst ratings, insider trades, earnings breakdowns, -bull case, bear case. In like 30 seconds." -[Show app UI: search stock → AI analysis appearing] - -PROOF (17-22s): -"It's got a 4.8 star rating. 52,000 investors use it. -And the AI actually shows you WHERE it got the information." - -CTA (22-27s): -"It's free to download. Link is in my bio." -[Text overlay: "Download Bloom — Free"] -``` - -#### Template 2: "Did You Know?" (Information Gap) - -``` -HOOK (0-2s): -[Text overlay: "90% of investors miss this"] -[Voice]: "Did you know you can see exactly what company insiders -are buying and selling?" - -PROBLEM (2-6s): -"CEOs and board members buy their own stock before it goes up. -It's all public data. But most people don't know where to find it." - -SOLUTION (6-16s): -"This app is called Bloom. It tracks every insider trade and -sends you an alert when an executive makes a big buy." -[Show app: insider trading screen with real data] - -PROOF (16-20s): -"Last month it flagged three stocks where insiders were loading up. -All three are up double digits." - -CTA (20-25s): -"Free download, link in bio." -[Text overlay: "Bloom — Free Stock Research"] -``` - -#### Template 3: "Hot Take / Contrarian" (Opinion-Led) - -``` -HOOK (0-2s): -[Text overlay: "Unpopular opinion"] -[Voice]: "If you're still using Yahoo Finance for stock research, -you're doing it wrong." - -PROBLEM (2-6s): -"Yahoo gives you a wall of numbers with no context. -You still have to figure out what it all means yourself." - -SOLUTION (6-15s): -"There's this AI app that actually EXPLAINS the numbers. -You search Tesla and it tells you: here are the 3 reasons analysts -are bullish, here's the bear case, here's what insiders are doing." -[Show app UI] - -PROOF (15-19s): -"4.8 stars. Over 50,000 investors." - -CTA (19-23s): -"Download Bloom free. Link in bio." -``` - -#### Template 4: "Screen Recording" (Product Demo) - -``` -HOOK (0-2s): -[Screen recording starting mid-action] -[Text overlay: "How I research stocks in 30 seconds"] - -DEMO (2-20s): -[Record actual app usage]: -- Open Bloom -- Search "NVDA" -- Show AI analysis loading -- Scroll through analyst ratings -- Show insider trading data -- Show earnings breakdown - -[Voice over the recording]: -"Search any stock. Boom — full AI breakdown. Analyst ratings -right here. Insider trades. Earnings surprises. -This would've taken me an hour on Yahoo Finance." - -CTA (20-25s): -"App is called Bloom. Free download." -[Text overlay: "Bloom — Link in Bio"] -``` - -### Viral Hook Principles (validated: 18M views, zero audience, zero budget) - -These four rules override any template when there's a conflict. A solo dev applied them to get 18M YouTube Shorts views in 28 days from scratch. - -**1. The hook is about the viewer, not the product.** -Every ad that flops opens with the product's features. Every ad that goes viral opens with something the viewer experiences, fears, wants, or wonders about themselves. -- ❌ "Bloom's AI analyzes every stock for you" (about the product) -- ✅ "I let an AI pick my stocks for 30 days and I wasn't ready for what it found" (about the experience) - -**2. Broad angle > niche angle.** -"Investing app" reaches investors. "What if you could see what hedge funds buy before it hits the news" reaches anyone with money. Find the universal human experience (FOMO, insider edge, outsmarting the system, proving someone wrong) that your product connects to. - -**3. Build a curiosity gap — tease early, reveal late.** -Introduce a question or result in the first 3 seconds that you don't answer until the final seconds. People don't stay for the product — they stay because they need the answer. The app demo is just something to look at while they wait. -- Bad: Reveal the stock pick in second 5, then explain it for 25 seconds. -- Good: "This AI bought a stock I would never have touched. Here's what happened." → Show the analysis → reveal the result at 25 seconds. - -**4. Every line earns the next.** -If a line explains or teaches without escalating tension, cut it. Information is the reward at the end, not the scaffolding. Read the script line by line — each line should make the viewer more curious, not more informed (until the end). - ---- - -### TikTok-Specific Rules - -1. **Vertical video only** (9:16). No letterboxing. -2. **Text on screen from frame 1.** Audio might be off. -3. **No logos in the first 3 seconds.** It signals "ad" and gets skipped. -4. **Native feel > polished.** Film on phone, not studio. Talk to camera, not at camera. -5. **The hook IS the ad.** If the first 2 seconds don't land, nothing else matters. -6. **Music/trending sound under the voiceover.** Boosts distribution. -7. **CTA = "Link in bio"** (TikTok doesn't support clickable links in organic, only Spark Ads or paid). - -### Meta (Facebook/Instagram) Specific Rules - -1. **Square (1:1) or vertical (4:5) for feed.** 9:16 for Stories/Reels. -2. **Design for sound-off.** Captions/text overlays on all dialogue. -3. **First 3 seconds must work as a static image** (feed autoplay is often paused). -4. **CTA button text matters.** "Download" converts better than "Learn More" for apps. -5. **Carousel ads**: Each card = one benefit. Card 1 = hook. Last card = CTA. - -#### Template 5: "Emotional Arc" (5-Beat Progression) - -Longer-form video (30-35s) with deliberate energy shifts that mirror how real people talk about discoveries. Each beat has a distinct emotional tone. - -``` -BEAT 1: CURIOSITY (0-5s) — Moderate energy, conversational -"okay so I need to tell you about something I just found" -[Lean forward slightly. Interest, not hype. Approachable.] - -BEAT 2: FRUSTRATION (5-12s) — Energy dips, relatable pain -"because honestly I was spending hours reading analyst reports -and by the time I had a thesis, the stock already moved" -[Slight head shake. Slower pace. Authentic disappointment.] - -BEAT 3: DISCOVERY (12-20s) — Energy builds, genuine excitement -"then I found this app and literally within the first search -I got a full AI breakdown: bull case, bear case, insider trades" -[Show app UI. Brightening expression. Faster pace.] - -BEAT 4: VALIDATION (20-28s) — Peak energy, confidence -"like it's showing me what company CEOs are buying before -the stock moves, and it cites every source so I can verify" -[Animated hand gestures. Direct eye contact. This is the proof.] - -BEAT 5: RECOMMENDATION (28-35s) — Warm, direct, slightly lower -"if you do any kind of stock research, just try it. -it's called Bloom. free download. you can thank me later" -[Friendly but confident. Natural conclusion, not a hard sell.] -``` - -**Why the arc matters:** Flat energy = fake. Real testimonials have emotional dynamics. The dip at beat 2 makes the excitement at beats 3-4 feel earned. The slight cooldown at beat 5 signals authenticity (hard sells stay at peak energy, which viewers have learned to distrust). - -**Adaptation for shorter formats (15-20s):** Collapse beats 1+2 into a single "problem hook" (0-5s) and beats 4+5 into "proof + CTA" (15-20s). Keep beat 3 (discovery) as the core. - -### Video Ad Anti-Patterns - -- ❌ Starting with your logo or brand name (instant skip) -- ❌ "Hey guys, so today I want to talk about..." (zero hook) -- ❌ Background music louder than voice -- ❌ Cramming 10 features into 30 seconds (pick 2-3) -- ❌ Professional studio lighting for organic-style content (feels like an ad) -- ❌ Showing the app for more than 15 seconds without voiceover context -- ❌ Ending without a CTA -- ❌ "Check it out" as a CTA (check WHAT out WHERE?) - ---- - -### Geo-Targeted Ads: Regional Localization - -When running Meta paid ads to specific regional markets (city/radius targeting), localize the script — not just the targeting. Same product, different frame. - -**Three elements to adapt per regional variant:** - -1. **Industry context in the hook** — reference dominant local industry in the problem beat - - Memphis → logistics, distribution, supply chain - - Nashville → healthcare, insurance, medical admin - - Richmond → financial services, insurance - - Boise → independent retail, service businesses - - Phoenix → construction, real estate, professional services - -2. **Business size framing** — regional markets skew smaller teams; adjust "person like me" framing - - "managing a team of 8 to 15 people" > generic professional framing - -3. **Tone register** - - Southern markets: warmer, relationship-oriented, less efficiency jargon - - Northern/western: direct, outcome-first, efficiency-focused - - Midwest: practical, skeptical of hype - -**Production:** With AI UGC (see `references/7-ugc-script-templates.md`), regional variants are near-zero marginal effort — adapt hook + framing + tone, regenerate voice, redeploy. Test 8-12 markets simultaneously, concentrate paid budget on organic traction winners. diff --git a/ad-copy/references/5-push-notifications.md b/ad-copy/references/5-push-notifications.md deleted file mode 100644 index 311d1d9..0000000 --- a/ad-copy/references/5-push-notifications.md +++ /dev/null @@ -1,76 +0,0 @@ -# 5. Push Notifications - -Push notifications are the highest-converting channel you have. They're also the fastest way to get uninstalled. Respect them. - -### Rules - -1. **Every push must deliver value or trigger action.** No "We miss you!" garbage. -2. **Personalize.** "NVDA just got upgraded to Buy" > "Check out new analyst ratings" -3. **Timing matters.** Market hours for market events. Never push at 3 AM. -4. **Frequency cap.** Max 1-2/day for engaged users. Max 2-3/week for casual users. -5. **Deep link to the relevant screen.** Don't push about insider trades and drop them on the home screen. - -### Templates by Type - -#### Trigger-Based (Highest Value) - -Fired by real events on stocks the user watches. - -``` -ANALYST UPGRADE: -Title: "NVDA Upgraded to Buy" -Body: "Goldman Sachs upgraded NVIDIA with a $180 price target. See the full analysis." - -INSIDER TRADE: -Title: "AAPL CEO just bought $10M in stock" -Body: "Tim Cook purchased 50,000 shares at $198. Largest insider buy this quarter." - -EARNINGS BEAT: -Title: "TSLA beat earnings by 15%" -Body: "Revenue $25.7B vs $24.2B expected. AI breaks down the call highlights." - -PRICE ALERT: -Title: "AMZN hit your $200 target" -Body: "Amazon crossed $200 for the first time since March. Tap to see what changed." -``` - -#### Feature Announcements - -``` -NEW FEATURE: -Title: "New: AI Earnings Analysis" -Body: "Bloom now breaks down earnings calls in real-time. Try it with AAPL's report tonight." - -IMPROVEMENT: -Title: "Stock search is 2x faster" -Body: "We rebuilt search from scratch. Try it — search any of 6,000+ tickers." -``` - -#### Re-engagement - -Only send after 7+ days of inactivity. Require a hook. - -``` -MARKET EVENT: -Title: "Markets dropped 3% today" -Body: "Your watchlist has 4 stocks down over 5%. Tap to see which analysts are upgrading." - -MISSED ALERT: -Title: "2 stocks on your watchlist got upgraded" -Body: "While you were away, MSFT and GOOGL received analyst upgrades. See details." - -SEASONAL: -Title: "Earnings season starts Monday" -Body: "243 companies report this week, including 3 on your watchlist. Set your alerts." -``` - -#### Push Anti-Patterns - -- ❌ "We miss you! Come back!" (guilt trip, zero value) -- ❌ "Check out what's new in Bloom" (what IS new? be specific) -- ❌ "Investing tip of the day" (unsolicited, not personalized) -- ❌ Pushing the same message to all users (segment or don't push) -- ❌ More than 3 pushes in a day (instant uninstall territory) -- ❌ Pushing at 2 AM about non-urgent features - ---- diff --git a/ad-copy/references/6-email-sequences.md b/ad-copy/references/6-email-sequences.md deleted file mode 100644 index f41a57b..0000000 --- a/ad-copy/references/6-email-sequences.md +++ /dev/null @@ -1,253 +0,0 @@ -# 6. Email Sequences - -Email is the workhorse of conversion. Not for newsletters (that's content marketing). These are action-driving sequences tied to specific user lifecycle stages. - -### Welcome Sequence (Post-Download, 5 emails over 10 days) - -**Email 1: Immediate (within 5 minutes of download)** - -``` -Subject: Your first stock research is waiting (26 chars + emoji optional) -Preview: Search any stock and get an instant AI breakdown - -Body: -Welcome to Bloom. - -Here's how to get your first insight in 60 seconds: - -1. Open the app -2. Search any stock (try one you own) -3. Read the AI breakdown: bull case, bear case, key metrics - -That's it. You just did in 30 seconds what used to take 30 minutes. - -[CTA Button: "Open Bloom"] - -— Eric, Founder - -P.S. Reply to this email if you have questions. I read every one. -``` - -**Email 2: Day 2 (Feature highlight)** - -``` -Subject: The feature 90% of new users miss -Preview: Most people don't set this up and regret it - -Body: -Most Bloom users don't set up alerts until after they miss a big move. - -Set up a watchlist alert in 20 seconds: -1. Add stocks to your watchlist -2. Tap the bell icon on any stock -3. Choose: analyst upgrades, insider trades, earnings, or price targets - -Last week, Bloom users got alerted to 47 analyst upgrades before the -market opened. - -[CTA Button: "Set Up Alerts"] -``` - -**Email 3: Day 4 (Social proof)** - -``` -Subject: What 52,000 investors found in Bloom -Preview: Real results from real users - -Body: -Bloom has a 4.8★ rating from 2,400+ reviews. Here's what investors say: - -"Found an insider buying pattern I never would've caught on my own." -"Replaced Seeking Alpha, Yahoo Finance, and 2 hours of morning research." -"The AI doesn't just summarize — it actually tells you what matters." - -The pattern: investors who research at least 3 stocks in their first -week are 4x more likely to keep using Bloom daily. - -You've researched [X] so far. Try 3 more today. - -[CTA Button: "Research a Stock"] -``` - -**Email 4: Day 7 (Value expansion)** - -``` -Subject: You're using 20% of Bloom -Preview: 3 features most users discover late - -Body: -You've been using Bloom for a week. Here are 3 things you probably -haven't tried yet: - -1. ASK THE AI A QUESTION -Type a question like "Is NVDA overvalued?" and get a sourced answer. -Not ChatGPT guessing — Bloom cites actual filings and data. - -2. COMPARE STOCKS -Search a stock and tap "Compare." Side-by-side analysis with AI -commentary on which metrics matter most. - -3. EARNINGS CALENDAR -See every upcoming earnings date for your watchlist. -Get the AI breakdown within minutes of the announcement. - -[CTA Button: "Try These Features"] -``` - -**Email 5: Day 10 (Upgrade push, if on free tier)** - -``` -Subject: Your free research limit resets tomorrow -Preview: Or unlock unlimited with Premium - -Body: -You've used [X] of your [Y] free AI research conversations this week. - -Here's what Premium unlocks: -✓ Unlimited AI research conversations -✓ Real-time insider trading alerts -✓ Advanced stock screeners -✓ Full analyst rating history - -50% off your first month: [LINK] - -Free users who upgrade within the first 2 weeks are the most active -investors on the platform. They research 3x more stocks. - -[CTA Button: "Get 50% Off Premium"] - -Not ready? No pressure. Your free tier resets tomorrow. Keep researching. -``` - -### Trial-to-Paid Conversion (3 emails during trial) - -**Email 1: Day 1 of trial** - -``` -Subject: Your Premium trial is live -Preview: Here's how to get the most out of the next 14 days - -Body: -You've got 14 days of Bloom Premium. Here's the fastest way to see -the difference: - -1. Search a stock you're considering buying -2. Read the full AI analysis (Premium shows 3x more depth) -3. Check the insider trading tab (Premium-only real-time data) -4. Set a smart alert for analyst rating changes - -Premium users research 3x more stocks and catch moves 2 days earlier -than free users on average. - -[CTA Button: "Start Researching"] -``` - -**Email 2: Day 10 (urgency + proof)** - -``` -Subject: 4 days left on your trial -Preview: Here's what you'll lose on [date] - -Body: -Your Premium trial ends in 4 days. - -Here's what goes away: -✗ Unlimited AI conversations (back to 5/day) -✗ Real-time insider trading data -✗ Advanced screeners -✗ Full analyst rating history - -During your trial, you've: -• Researched [X] stocks -• Received [Y] alerts -• [Personalized stat] - -Keep everything for $X/month. That's less than one Seeking Alpha -subscription. - -[CTA Button: "Keep Premium"] -``` - -**Email 3: Day 14 (last day)** - -``` -Subject: Your trial ends tonight -Preview: Lock in 50% off before midnight - -Body: -Premium expires at midnight. - -Last chance: 50% off your first 3 months. - -[CTA Button: "Lock In 50% Off"] - -After tonight: $X/month. Cancel anytime in one tap. -``` - -### Win-Back Sequence (users inactive 14+ days, 3 emails) - -**Email 1: Day 14 of inactivity** - -``` -Subject: NVDA got 3 analyst upgrades while you were away -Preview: Your watchlist had 7 alerts you missed - -Body: -While you were away, here's what happened to your watchlist: - -• NVDA: 3 analyst upgrades, price target raised to $180 -• AAPL: CEO bought $5M in stock -• TSLA: Beat earnings by 12% - -You missed these alerts because you haven't opened Bloom in 2 weeks. - -[CTA Button: "See What You Missed"] -``` - -Use real data from their watchlist. Generic "we miss you" emails get deleted. - -**Email 2: Day 21** - -``` -Subject: What changed in Bloom since you left -Preview: 2 new features you haven't seen - -Body: -We shipped 2 features since your last visit: - -1. [Newest feature with one-line benefit] -2. [Second newest feature with one-line benefit] - -Plus: your watchlist is still active and tracking [X] stocks. - -[CTA Button: "Open Bloom"] -``` - -**Email 3: Day 30 (final attempt)** - -``` -Subject: Should we keep your watchlist active? -Preview: We'll archive it in 7 days unless you log in - -Body: -You have [X] stocks on your watchlist with [Y] unread alerts. - -We'll keep tracking them for 7 more days. After that, we'll -pause alerts to save your battery and inbox. - -Want to keep them? Just open the app. - -[CTA Button: "Keep My Watchlist"] -``` - -### Email Anti-Patterns - -- ❌ "Dear Valued Customer" (use their name or nothing) -- ❌ Emails longer than 200 words (mobile readers, max 150 is better) -- ❌ Multiple CTAs in one email (one email, one action) -- ❌ HTML-heavy templates that look like ads (plain text converts better for lifecycle emails) -- ❌ Sending the same email to all users regardless of behavior -- ❌ "Unsubscribe to stop receiving these" buried in 6pt font (make it easy and honest) -- ❌ Subject lines that don't relate to body content (bait-and-switch kills trust) - ---- diff --git a/ad-copy/references/7-ugc-script-templates.md b/ad-copy/references/7-ugc-script-templates.md deleted file mode 100644 index 6e713d8..0000000 --- a/ad-copy/references/7-ugc-script-templates.md +++ /dev/null @@ -1,195 +0,0 @@ -# 7. UGC Script Templates (AI-Generated Video) - -Script structures for AI-generated UGC testimonials. These pair with the Sora product integration pipeline (`sora/references/ugc-product-integration.md`) for full video production. - -## AI UGC Production Stack - -Before scripting, build the production infrastructure. See `whop-content-rewards` skill for full detail. Summary: - -**1. Find a reference ad first** -- Use [Meta Ad Library](https://facebook.com/ads/library) or [GetHooked.ai](https://gethooked.ai) — find ads in your category running 30+ days (run duration = proof of return) -- Watch 3x: map hook → product intro → proof → CTA structure explicitly. Use it as the script architecture, not a blank page. - -**2. Generate a credible avatar** -- Presenter = peer to target audience, not a spokesperson or actor -- For Bloom: working investor in their 30s, not a finance bro or formal advisor -- Tools: Midjourney, HeyGen. Generate 4–6 variants, pick the best demographic match. - -**3. Voice match precisely** -- Mismatch in age/energy/tone creates subconscious friction — viewers feel it without identifying it -- Tool: ElevenLabs (best micro-variation and pacing control) -- Test: place avatar image on screen, play voice samples — "can I genuinely imagine this person talking like this?" -- After generating: remove silences (Adobe Premiere silence removal) — trims 20–30s off a 3-min VO, improves pacing - -**4. Native caption formatting** -- 50–80% of Instagram viewers encounter content muted first — captions are not optional -- Use Instagram's native story text style (semi-transparent dark background) — brain registers it as organic, not ad -- Technique: generate inside Instagram app on throwaway photo → import into editor → remove background → overlay - ---- - -## Emotional Beat Structure - -Every UGC testimonial follows an emotional arc, not a flat pitch. Each beat has a specific energy level and purpose. - -``` -CURIOSITY (0-3s) — Moderate energy. Hook with intrigue, not hype. -PROBLEM (3-10s) — Energy dips. Frustration, relatability, empathy. -DISCOVERY (10-20s) — Energy builds. Hope, specific benefit, shift from frustration. -VALIDATION (20-28s) — Peak energy. Results, social proof, personal transformation. -CTA (28-35s) — Sustained but slightly softer. Clear next step, friendly not pushy. -``` - -The energy dip at PROBLEM is what makes DISCOVERY feel earned. Skip the dip and the whole thing sounds like an infomercial. - -## Template A: Pain Point Discovery (Excited Tone) - -**Actor direction:** Animated, talking fast, genuine surprise energy. - -``` -CURIOSITY (0-3s): -"Okay this is wild..." -[Text overlay: core claim or stat] - -PROBLEM (3-10s): -"I was literally spending [$ amount] on [competitor/old solution] -that barely worked. I tried [alternative 1], [alternative 2], -nothing actually fixed [specific pain]." - -DISCOVERY (10-20s): -"Then I found [product] and it completely changed everything. -Within [timeframe] I noticed [specific result]. -Like, [concrete detail only a real user would mention]." - -VALIDATION (20-28s): -"I'm seeing [specific outcome] I didn't think were possible. -Everyone around me has noticed. [Social proof detail]." - -CTA (28-35s): -"If you're dealing with [problem], seriously just try this. -You can thank me later." -[Text overlay: product name + where to get it] -``` - -## Template B: Social Proof Skeptic (Contemplative Tone) - -**Actor direction:** Calm, thoughtful, measured delivery. Credibility through restraint. - -``` -CURIOSITY (0-3s): -"So everyone's been talking about [product]..." - -PROBLEM (3-10s): -"And honestly I was skeptical because I've tried everything. -[Specific thing they tried]. [Another thing]. None of it stuck." - -DISCOVERY (10-20s): -"But after using it for [timeframe] I totally get the hype now. -The difference is [specific observable change]. -[Detail that shows actual usage, not marketing speak]." - -VALIDATION (20-28s): -"I'm actually recommending it to people, which I never do. -[Specific person or context where they recommended it]." - -CTA (28-35s): -"If you've been on the fence, this is the one." -[Text overlay: product name + CTA] -``` - -## Template C: Unboxing Reveal - -**Actor direction:** Excited anticipation → genuine reaction. Five segments, each gets its own video generation pass. - -``` -INTRO (0-10s): -"Okay so this just arrived and I'm actually so excited. -I've been hearing about [product] everywhere. -Everyone says it's completely different from [competitor]. -Let's see if it lives up to the hype." -[Talking head, selfie-style, package visible but unopened] - -UNBOXING (10-18s): -[POV overhead shot: hands opening package] -[First glimpse of product] -[Packaging details visible] -— No voiceover needed. Let the reveal breathe. - -FEATURES (18-30s): -[Actor holding product, examining it] -"Okay so right away I notice [physical quality detail]. -The [specific feature] is [observation]. -And look at [detail] — that's [comparison to competitor]." -[Multi-angle: front → side → detail closeup] - -DEMO (30-42s): -[Actor using the product in context] -[Show application/consumption/interaction] -"So [describing the experience in real time]. -[Genuine reaction to the experience]." - -VERDICT (42-50s): -"Honestly this exceeded my expectations. -If you've been considering [category], this is the one. -I'm already planning to [repeat purchase/recommend/etc]." -[Text overlay: product name + CTA] -``` - -**Production note:** Each segment is a separate video generation + composite pass. The unboxing POV (segment 2) uses a different camera angle than the talking head segments. - -## Template D: Lifestyle Context (Soft Sell) - -**Actor direction:** Natural, candid, product integrated into daily life rather than pitched. - -``` -CONTEXT (0-5s): -[Actor in natural environment: commuting, cooking, at desk, working out] -"So my [morning routine / commute / workout / evening] has been -completely different since I started using [product]." - -INTEGRATION (5-15s): -[Show product in use within the environment] -"I just [how they use it: take it, apply it, open it, check it] -and [immediate benefit]. It takes [time: seconds/minutes]." -[Product visible but not centered — lifestyle first, product second] - -CONTRAST (15-22s): -"Before I was [old behavior: slower, more complicated, worse results]. -Now I [new behavior]. [Specific metric or observable difference]." - -CLOSE (22-28s): -"Honestly it's one of those things where you wonder -why you didn't switch sooner." -[Text overlay: product name] -``` - -## Script Adaptation Rules - -**For different tones**, adjust these variables: -- **Excited:** Shorter sentences, interruptions ("like, wait"), faster pacing -- **Contemplative:** Longer pauses, qualifiers ("honestly," "actually"), measured delivery -- **Casual:** Filler words ("so," "like"), tangents that circle back, lower stakes language -- **Urgent:** Statistics, deadlines, scarcity cues, direct address ("you need to") - -**For different products**, adjust the PROBLEM beat: -- **Replacing a competitor:** Name the old solution's specific failure -- **New category:** Describe the gap ("I didn't even know this existed") -- **Upgrade:** Describe what they tolerated before ("I just accepted that...") -- **Impulse/lifestyle:** Skip PROBLEM, extend DISCOVERY with sensory details - -**For different durations:** -- **15 seconds:** CURIOSITY (2s) → DISCOVERY (8s) → CTA (5s). Skip PROBLEM and VALIDATION. -- **30 seconds:** Full structure, compressed. One sentence per beat. -- **45-60 seconds:** Full structure with room for details. Add second VALIDATION beat or DEMO segment. - -## Bloom-Specific Adaptations - -These templates work for Bloom ads by replacing generic placeholders: - -| Beat | Bloom-Specific Content | -|------|----------------------| -| PROBLEM | "Hours on Yahoo Finance, Reddit, Seeking Alpha. By the time I had a thesis, the stock already moved." | -| DISCOVERY | "Search any ticker. Full AI breakdown in 30 seconds: analyst ratings, insider trades, earnings, bull/bear case." | -| VALIDATION | "4.8 stars. 52,000 investors. The AI shows you WHERE it got the information." | -| CTA | "Free to download. Link in bio." | -| DEMO | Screen recording of Bloom: search NVDA → AI analysis → insider trades → earnings | diff --git a/ad-copy/references/a-b-testing-framework.md b/ad-copy/references/a-b-testing-framework.md deleted file mode 100644 index 706a240..0000000 --- a/ad-copy/references/a-b-testing-framework.md +++ /dev/null @@ -1,87 +0,0 @@ -# A/B Testing Framework - -Test systematically. Most teams test randomly and learn nothing. - -### What to Test (In This Order) - -Testing priority ranked by conversion impact: - -| Priority | Element | Why | Min Sample | -|----------|---------|-----|-----------| -| 1 | **Headlines / Hooks** | Determines if anyone reads the rest | 500 per variant | -| 2 | **Hero image / Video thumbnail** | Determines if anyone clicks | 500 per variant | -| 3 | **CTA text and placement** | Determines if readers become users | 300 per variant | -| 4 | **Social proof** | Determines if uncertain visitors convert | 300 per variant | -| 5 | **Body copy** | Determines conversion rate for engaged readers | 1,000 per variant | -| 6 | **Pricing / Offer** | Determines revenue per conversion | 1,000 per variant | -| 7 | **Page layout** | Marginal gains after the above are optimized | 2,000 per variant | - -### Statistical Significance - -Don't call a winner too early. You need: - -- **Minimum sample**: 300-500 conversions per variant (not impressions, CONVERSIONS) -- **Confidence level**: 95% minimum (p < 0.05) -- **Test duration**: At least 7 days (captures weekly behavior cycles) -- **One variable at a time**: Changing headline AND image means you don't know which worked - -**Quick significance check**: If Variant B is beating Variant A by less than 10% relative lift, you probably need 2,000+ conversions per variant to confirm it's real. Big wins (30%+ lift) are detectable faster. - -### Testing by Channel - -#### Google Ads -- Use RSA headline/description rotation (Google's built-in testing) -- Create separate ad groups for major copy themes, not just keyword groups -- Test landing pages with Campaign Experiments (50/50 split) -- Run for 2+ weeks before judging (Google's learning period) - -#### App Store -- Use Apple's Product Page Optimization (3 treatments) -- Test screenshot order and text (highest impact) -- Test icon variants (second highest) -- Run for minimum 7 days, Apple recommends 14 -- Google Play: use Store Listing Experiments (up to 5 variants) - -#### TikTok / Meta -- Same video with 3 different hooks (first 2-3 seconds) -- Test CTA text: "Download Free" vs "Try It Free" vs "Get the App" -- Test thumbnail/first frame for feed placement -- Budget: min $50/day per variant for 5+ days - -#### Email -- Subject line A/B test on 20% of list, send winner to remaining 80% -- Test send time: 7 AM vs 10 AM vs 6 PM (user timezone) -- CTA button color is NOT worth testing until everything above is optimized -- Min list size per variant: 1,000 (for open rate), 5,000 (for click rate) - -#### Landing Pages -- Use UTM parameters to track which traffic source converts -- Test one element at a time (hero copy OR CTA text, not both) -- Run tests for full business cycles (7-14 days minimum) -- Tools: Google Optimize (free), VWO, Optimizely - -### Rapid Creative Testing (4-Day Blitz) - -For paid social (Meta/TikTok), the traditional test cycle is too slow: brief creators → wait for delivery → launch → wait for data → iterate = 4 weeks for 3 variations. This protocol gets 30 variations tested in 4 days: - -**Day 1: Generate 20 creative variations.** -Build a testing matrix: 3-5 different visual styles × 4-6 narrative angles × 2-3 emotional tones. Use Nano Banana Pro for visual cards, Larry for TikTok slideshows, screen recordings for demo variants. One operator, one day, 20 ads. - -**Day 2: Launch all 20 simultaneously.** -$20-50/day per variant. Broad targeting. Let the algorithm sort. Don't pre-judge which will win (you'll be wrong). - -**Day 3: Identify top 3-5 performers.** -Kill the bottom 75% based on CTR and conversion data. Don't wait for statistical significance on losers; you're looking for signal, not proof. - -**Day 4: Generate 10 iterations of winners.** -Take each winner's hook, angle, and format. Create variations: different opening lines, different proof points, different CTAs. Launch immediately. This is your second-generation creative set. - -**Why this works:** Traditional ugc costs $200-800 per video and 7-14 day turnaround. AI-generated creative (Nano Banana Pro for images, screen recordings for demos, Larry for slideshows) costs $2-8 per asset and takes minutes. The volume advantage means you find winners 10x faster. - -**Cadence:** Run a 4-day blitz at launch, then weekly 10-variation refreshes to fight creative fatigue. Every 60-90 days, run a full blitz with new angles. - -### The Testing Log - -Keep a testing log. Every test. - -```markdown diff --git a/ad-copy/references/brand-voice-reference.md b/ad-copy/references/brand-voice-reference.md deleted file mode 100644 index b383766..0000000 --- a/ad-copy/references/brand-voice-reference.md +++ /dev/null @@ -1,27 +0,0 @@ -# Brand Voice Reference - -**Read `~/marketing/WRITING-STYLE.md`** before writing any copy. Bloom's voice is concrete, specific, honest, and irreverent. Even in ads, we sound like a smart friend, not a corporation. "Start investing smarter" is generic. "See exactly why Tesla dropped 12% before your coworker does" is Bloom. - -## Voice and Tone Matrix - -Before writing, pin the brand on each axis. Bloom's defaults shown — adjust per context (e.g., error states skew more serious; TikTok skews more casual). - -| Axis | ← | → | Bloom default | -|------|---|---|---------------| -| Tone | Funny | Serious | 30% funny / 70% serious | -| Register | Casual | Formal | Casual | -| Edge | Irreverent | Respectful | Leans irreverent | -| Energy | Enthusiastic | Matter-of-fact | Matter-of-fact (facts > hype) | - -Use this to gut-check drafts: does the copy land where it should on each axis? If a line reads too corporate (formal + respectful + serious), it's off-brand. - -## Messaging Hierarchy - -Work top-down when building a campaign. Each level feeds the next. - -1. **Tagline** — one sentence, timeless, brand-level (e.g., "Invest like you mean it") -2. **Value proposition** — what the product does and for whom, one sentence -3. **Key messages** — 3 proof points that back the value prop -4. **Proof points** — specific data, stories, or stats that make each key message credible - -Don't skip to proof points. If the value prop is unclear, the proof points won't land. diff --git a/ad-copy/references/copy-anti-patterns-kill-on-sight.md b/ad-copy/references/copy-anti-patterns-kill-on-sight.md deleted file mode 100644 index 8215822..0000000 --- a/ad-copy/references/copy-anti-patterns-kill-on-sight.md +++ /dev/null @@ -1,66 +0,0 @@ -# Copy Anti-Patterns (Kill on Sight) - -These patterns kill conversions. If you see them in any draft, rewrite immediately. - -### Feature Listing Without Benefits -``` -❌ "AI-powered analysis, real-time data, watchlists, alerts, screeners" -✅ "Research any stock in 30 seconds. AI reads the filings so you don't have to." -``` -Features are ingredients. Benefits are the meal. Nobody orders "flour, eggs, sugar." They order cake. - -### Being Clever Instead of Clear -``` -❌ "Where alpha meets artificial intelligence" -✅ "AI stock research. Search any stock, get the full picture." -``` -Clever copy makes the writer feel smart. Clear copy makes the reader take action. Every time you're tempted to be clever, ask: "Would my mom understand what this app does from this sentence?" - -### Burying the CTA -``` -❌ [500 words of features] ... [CTA at very bottom] -✅ [Headline] → [CTA] → [Supporting evidence] → [CTA again] -``` -Put the CTA within the first scroll. Then repeat it after every major section. Some people decide fast. Let them. - -### Weak CTAs -``` -❌ "Learn More" → learn more about WHAT? -❌ "Get Started" → started with WHAT? -❌ "Click Here" → nobody says "click here" in 2026 -❌ "Submit" → sounds like surrendering -❌ "Sign Up" → sounds like homework - -✅ "Download Bloom Free" → specific action + product + risk reversal -✅ "Start Investing Smarter" → benefit-driven -✅ "Research Your First Stock" → specific, immediate value -✅ "Get the App — It's Free" → action + risk reversal -``` - -### No Social Proof -If your landing page / ad / listing doesn't include at least ONE of these, it's incomplete: -- User count ("52,000 investors") -- Star rating ("4.8★ from 2,400+ reviews") -- Specific user result ("Found a 40% undervalued stock") -- Press mention ("Featured in TechCrunch") - -### Vague Value Props -``` -❌ "Powerful tools for smart investing" → what tools? how powerful? -❌ "Take control of your financial future" → means nothing specific -❌ "Invest with confidence" → cliché, no specifics -❌ "Your all-in-one investing solution" → every app says this - -✅ "AI reads 10-K filings so you don't have to" → specific, tangible -✅ "See analyst rating changes before the market opens" → specific timing -✅ "Search 6,000+ stocks. Get a breakdown in 30 seconds." → specific scope + speed -``` - -### The "We" Problem -``` -❌ "We built Bloom to help investors research smarter" -✅ "Research any stock in 30 seconds" -``` -The reader doesn't care about you. They care about what they get. Lead with "you" and the benefit, not "we" and the origin story. - ---- diff --git a/ad-copy/references/copy_frameworks.md b/ad-copy/references/copy_frameworks.md deleted file mode 100644 index b4de7dd..0000000 --- a/ad-copy/references/copy_frameworks.md +++ /dev/null @@ -1,568 +0,0 @@ -# Copywriting Frameworks Reference - -This document contains 14 proven copywriting frameworks with selection guidance based on copy type, platform, and use case. - ---- - -## Framework Selection Matrix - -Use this matrix as a starting point — most frameworks work across multiple contexts. Choose based on your angle and audience awareness level. - -| Copy Type | Strong Options | Also Works Well | -|-----------|----------------|-----------------| -| Facebook/Instagram Ads | AIDA, PAS, BAB | FAB, 5-Point, G.R.A.B | -| TikTok/Reels/Shorts | G.R.A.B, PAS, SLAP | BAB, STAR Story | -| YouTube Pre-roll | AIDA, PAS | BAB, 5-Point | -| YouTube Long-form | PASTOR, AIDA | 5-Point, ACCA | -| Landing Pages | PAS, AIDA, BAB | PASTOR, 5-Point | -| Sales Pages (Long-form) | PASTOR, AIDA, 5-Point | PAS, BAB | -| Email Sequences | PAS, AIDA, QUEST | BAB, ACCA | -| LinkedIn Posts | BAB, AIDA, PAS | FAB, ACCA | -| E-commerce Product Ads | FAB, AIDA, PAS | BAB, 5-Point | -| Transformation/Coaching | BAB, PAS, PASTOR | AIDA, 4P | -| B2B/SaaS Ads | ACCA, PAS, AIDA | BAB, FAB | -| UGC/Influencer Scripts | STAR Story, PAS, G.R.A.B | BAB, AIDA | -| Retargeting Ads | QUEST, PAS, SLAP | AIDA, BAB | -| Advertorials | PASTOR, AIDA | 5-Point, PPPP | -| Product Launch | 5-Point, AIDA, PAS | BAB, FAB | -| Webinar/Event Promo | AIDA, PAS, BAB | 5-Point, QUEST | -| App Store Description | FAB, AIDA, PAS | BAB | -| Cold Outreach | PAS, BAB, AIDA | QUEST | -| Newsletter Promo | AIDA, PAS, 5-Point | BAB, QUEST | - ---- - -## Framework Details - -### 1. AIDA (Attention → Interest → Desire → Action) - -**The universal framework.** Works for almost any copy type. When in doubt, start here. - -**Works well for:** -- Social media ads (Facebook, Instagram, LinkedIn, Twitter/X) -- Landing pages and sales pages -- Email campaigns and newsletters -- YouTube ads and video scripts -- Product launches and announcements -- Webinar and event promotions -- Blog post intros and CTAs -- App store descriptions -- Print ads and billboards -- Pitch decks and presentations - -**Why it works:** Forces the classic funnel structure. Grabs attention, builds logical progression, creates desire, drives action. Flexible enough to adapt to any length or platform. - -**Use when:** You need a reliable structure that works anywhere. Great default when unsure which framework to use. - -**Structure:** -- **A - Attention:** Hook that stops the scroll. Bold claim, question, surprising stat, or pattern interrupt. -- **I - Interest:** Explain why this matters. Connect to their world. Build curiosity. -- **D - Desire:** Build emotional want. Show transformation, benefits, social proof. Make them feel the outcome. -- **A - Action:** Clear CTA. Tell them exactly what to do next. - -**Example (Facebook Ad):** -``` -[Attention] Tired of wasting money on ads that don't convert? -[Interest] Most businesses burn 60% of their ad budget on the wrong audience. -[Desire] Imagine knowing exactly who will buy before you spend a dollar. -[Action] Get our targeting framework free. Link in bio. -``` - -**Example (Landing Page Headline):** -``` -[Attention] Your competitors are stealing your customers while you sleep. -[Interest] 73% of buyers choose the first solution they find. -[Desire] Be that first solution with AI-powered SEO that ranks in 30 days. -[Action] Start your free trial → -``` - -**Example (Email Subject + Opening):** -``` -[Attention] Subject: The $50K mistake I made last quarter -[Interest] I thought more features = more sales. I was dead wrong. -[Desire] After cutting 40% of our product, revenue jumped 3x. -[Action] Here's the exact framework I used (steal it) → -``` - ---- - -### 2. PAS (Problem → Agitate → Solution) - -**The pain-driven powerhouse.** Fast, emotional, and direct. One of the most versatile frameworks. - -**Works well for:** -- Short-form social ads (Facebook, Instagram, TikTok, Twitter/X) -- UGC and influencer scripts -- Landing page headlines and hero sections -- Email subject lines and openers -- Cold outreach messages -- Product descriptions for problem-solving products -- LinkedIn posts -- Video ad scripts -- Sales page sections -- App notifications and push messages - -**Why it works:** Hits the emotional trigger hard and fast. Creates urgency through pain amplification. People are motivated more by avoiding pain than gaining pleasure. - -**Use when:** Your product solves a clear pain point. Works for SaaS, health, fitness, productivity, finance — anything where the "before" state hurts. - -**Structure:** -- **P - Problem:** State the pain clearly. Make them feel seen and understood. -- **A - Agitate:** Twist the knife. Show consequences of not solving it. Future-pace the pain. -- **S - Solution:** Present your product as the relief. Show the way out. - -**Example (Social Ad):** -``` -[Problem] Your calendar is chaos. Meetings eat your entire day. -[Agitate] Every hour wasted in pointless meetings is an hour you'll never get back. Your projects pile up. Your stress compounds. Your best ideas die in your inbox. -[Solution] TimeBlock AI automatically protects your focus time. No more death by calendar. -``` - -**Example (Cold Email):** -``` -[Problem] Hiring takes 3 months and burns $15K per role. -[Agitate] Meanwhile, your team is drowning, projects slip, and your best people start eyeing the door. -[Solution] Our pre-vetted talent pool fills roles in 2 weeks. Same quality, 70% less cost. -``` - -**Example (LinkedIn Post):** -``` -[Problem] Most founders work IN their business, not ON it. -[Agitate] You're the bottleneck. Every decision waits for you. Vacations feel impossible. Growth stalls at your capacity. -[Solution] Here's the delegation framework that freed up 20 hours of my week ↓ -``` - ---- - -### 3. BAB (Before → After → Bridge) - -**The transformation framework.** Perfect for showing the journey from pain to possibility. - -**Works well for:** -- Transformation-focused ads (fitness, coaching, courses) -- SaaS and productivity tools (show the workflow improvement) -- Case study formats -- LinkedIn posts and thought leadership -- Video testimonials structure -- Landing page hero sections -- Email sequences -- Sales conversations -- Before/after content -- Personal brand storytelling - -**Why it works:** Humans are wired for stories. BAB creates an instant mental movie of transformation. The "After" creates desire; the "Bridge" creates action. - -**Use when:** You want the viewer to instantly imagine the improved version of themselves or their business. - -**Structure:** -- **B - Before:** Paint their current painful reality. Make it specific and relatable. -- **A - After:** Show the transformed state they desire. Make it vivid and emotional. -- **B - Bridge:** Your product/solution is the path from before to after. - -**Example (Coaching/Course Ad):** -``` -[Before] 3 months ago, I was working 70-hour weeks and still behind on everything. -[After] Now I work 35 hours and my revenue doubled. -[Bridge] The difference? I replaced 12 tools with one system. Here's the exact setup. -``` - -**Example (SaaS Landing Page):** -``` -[Before] Before: Spreadsheets, sticky notes, and 47 browser tabs. Projects falling through cracks. -[After] After: One dashboard. Every task tracked. Nothing forgotten. Home by 6. -[Bridge] ProjectFlow is the system that makes it happen. Try it free. -``` - -**Example (LinkedIn Post):** -``` -[Before] 2 years ago I was mass-applying to jobs. 200 applications. 3 interviews. 0 offers. -[After] Last month I had 5 companies competing for me. Negotiated 40% above asking. -[Bridge] The difference? I stopped applying and started positioning. Here's how ↓ -``` - ---- - -### 4. FAB (Features → Advantages → Benefits) - -**The product-focused framework.** Translates specs into desire. - -**Works well for:** -- E-commerce product descriptions -- Tech and gadget ads -- SaaS feature announcements -- App store descriptions -- Product comparison pages -- Sales enablement materials -- Amazon listings -- Spec sheets that need to sell -- LinkedIn product posts -- Email product announcements - -**Why it works:** Quickly answers the three questions buyers ask: What is it? Why is it better? What do I get? Bridges the gap between features and emotional outcomes. - -**Use when:** Your product has clear features that drive tangible benefits. Great for tech, gadgets, software, and physical products. - -**Structure:** -- **F - Features:** What the product has or does (specs, capabilities, components). -- **A - Advantages:** Why that feature matters vs alternatives. The "so what?" -- **B - Benefits:** What the customer actually gets (emotional/practical outcome). - -**Example (E-commerce):** -``` -[Feature] 48-hour battery life. -[Advantage] Most headphones die in 8 hours. These last your entire work week. -[Benefit] Never interrupt your flow to charge. Just grab and go. -``` - -**Example (SaaS Feature):** -``` -[Feature] AI-powered inbox sorting. -[Advantage] Unlike filters that miss context, it learns what matters to YOU. -[Benefit] Start your day with the 5 emails that actually need attention. Ignore the rest. -``` - -**Example (App Store):** -``` -[Feature] Offline mode with full sync. -[Advantage] Competitors require constant internet. We don't. -[Benefit] Work from planes, subways, or that cabin with zero bars. Pick up exactly where you left off. -``` - ---- - -### 5. 4Cs (Clear → Concise → Compelling → Credible) - -**The editing framework.** Not a writing structure — a quality filter. - -**Use for:** Refining ANY copy written with another framework. Apply as a final polish. - -**Checklist:** -- **Clear:** Is the message instantly understandable? No jargon or ambiguity? -- **Concise:** Can any word be cut without losing meaning? Is every sentence earning its place? -- **Compelling:** Does it create desire or urgency? Would YOU click/buy/act? -- **Credible:** Is there proof? Stats? Social proof? Does it feel real? - -**Pro tip:** Read your copy aloud. If you stumble, it's not clear. If you're bored, it's not compelling. - ---- - -### 6. 5-Point Copy Formula (Promise → Picture → Proof → Push → Prompt) - -**The persuasion complete package.** Covers all bases: emotion, visualization, credibility, urgency. - -**Works well for:** -- Product launches and announcements -- Sales pages (short to medium length) -- Crowdfunding campaigns -- Course and program sales -- High-ticket offers -- Webinar pitches -- Facebook/Instagram ads with social proof -- Email sales sequences -- Landing pages with strong testimonials - -**Why it works:** Creates vivid desire AND backs it up with proof in one flow. Doesn't rely on just emotion or just logic — uses both. - -**Use when:** You have strong testimonials, case studies, or data to lean on. Great for offers where credibility drives conversion. - -**Structure:** -- **Promise:** Make a bold, specific claim about the outcome. -- **Picture:** Help them visualize having that outcome. Paint the scene. -- **Proof:** Back it up with testimonials, stats, case studies. -- **Push:** Create urgency. Why act now? -- **Prompt:** Clear, specific CTA. - -**Example (Course Sales):** -``` -[Promise] Double your email open rates in 14 days. -[Picture] Imagine waking up to replies from dream clients instead of crickets. Your inbox becomes a revenue stream, not a time sink. -[Proof] 2,400+ marketers have used this system. Average improvement: 127%. "Went from 12% to 41% opens in week one." — Sarah K. -[Push] We're closing enrollment Friday. Only 50 spots left at this price. -[Prompt] Grab your spot now → -``` - ---- - -### 7. PASTOR (Problem → Amplify → Story → Transformation → Offer → Response) - -**The long-form storyteller.** For when you need to build deep emotional connection. - -**Works well for:** -- Long-form sales pages -- Advertorials and native ads -- VSLs (video sales letters) -- Email sequences (spread across multiple emails) -- Complex products requiring education -- High-ticket coaching and consulting offers -- Webinar scripts -- Case study deep-dives - -**Why it works:** Story-driven and methodical. Builds emotional investment before asking for the sale. Perfect for higher-priced or complex offers. - -**Use when:** Your product needs narrative appeal, the buyer journey is longer, or you're selling something that requires trust. - -**Structure:** -- **P - Problem:** Identify and describe the pain in detail. -- **A - Amplify:** Make the problem feel urgent and serious. Stakes and consequences. -- **S - Story:** Tell a relatable story (yours or a customer's). -- **T - Transformation:** Show the before/after change vividly. -- **O - Offer:** Present your solution and everything they get. -- **R - Response:** Call to action with urgency or scarcity. - ---- - -### 8. ACCA (Awareness → Comprehension → Conviction → Action) - -**The educator's framework.** Teach first, sell second. - -**Works well for:** -- B2B and enterprise sales -- Complex SaaS products -- Financial services and insurance -- Technical products -- New category creation -- LinkedIn thought leadership -- Webinar funnels -- Email nurture sequences -- White paper lead-ins - -**Why it works:** Some products need explanation before desire. ACCA builds understanding first, then converts that understanding into conviction. - -**Use when:** The viewer needs context to appreciate your value. Great for innovative or technical products. - -**Structure:** -- **A - Awareness:** Make them aware of the problem or opportunity they didn't know existed. -- **C - Comprehension:** Help them understand the solution and how it works. -- **C - Conviction:** Build belief through proof, benefits, and trust signals. -- **A - Action:** Clear CTA. - -**Example (B2B SaaS):** -``` -[Awareness] 73% of B2B deals stall because buyers can't explain your product internally. -[Comprehension] Our platform auto-generates internal pitch decks your champions can share. One click, personalized for their stakeholders. -[Conviction] Used by Stripe, Notion, and 200+ B2B companies. Avg deal cycle reduced by 40%. -[Action] See how it works in 2 minutes → -``` - ---- - -### 9. QUEST (Qualify → Understand → Educate → Stimulate → Transition) - -**The nurturing framework.** For warm audiences who need a gentle push. - -**Works well for:** -- Retargeting campaigns -- Email nurture sequences -- Newsletter content -- LinkedIn posts (educational angle) -- Middle-of-funnel content -- Webinar follow-ups -- Community engagement - -**Why it works:** Qualifies + educates in a smooth sequence. Builds relationship before selling. Feels helpful, not pushy. - -**Use when:** You already have some user awareness or you're retargeting. Also great for filtering to ideal customers. - -**Structure:** -- **Q - Qualify:** Filter for your ideal audience. "This is for you if..." -- **U - Understand:** Show you understand their specific situation. -- **E - Educate:** Share valuable insight or information. -- **S - Stimulate:** Create desire for more or for the solution. -- **T - Transition:** Move them to the next step naturally. - ---- - -### 10. 4P (Picture → Promise → Prove → Push) - -**The fast converter.** Story + proof + action in tight package. - -**Works well for:** -- Conversion-heavy ads -- Retargeting -- Sales page sections -- Email CTAs -- Bold claims that need backing - -**Why it works:** Mixes emotion + logic + proof efficiently. Fast path from visualization to action. - -**Use when:** You want a quick path from story to CTA, but still need credibility. - -**Structure:** -- **Picture:** Paint a vivid scene of their desired outcome or current pain. -- **Promise:** Make a specific promise about what you'll deliver. -- **Prove:** Back it up with evidence. -- **Push:** Create urgency and CTA. - ---- - -### 11. PPPP (Picture → Promise → Prove → Push) - -**The dramatic storyteller.** Classic long-form format with big promises. - -**Works well for:** -- Long sales letters -- Traditional display ads -- Story-first campaigns -- Infomercial scripts -- Direct response campaigns - -**Why it works:** Proven "catalog copy" format. Creates emotional movie, makes bold promise, proves it, drives action. - -**Use when:** You want dramatic, story-first copy with big promises and have proof to back them. - ---- - -### 12. STAR Story Solution (Situation → Task → Action → Result → Solution) - -**The narrative framework.** Hero's journey in 60 seconds. - -**Works well for:** -- UGC and influencer content -- Video ads (TikTok, Reels, YouTube) -- Podcast ads -- Case study format -- Testimonial structures -- LinkedIn posts -- Founder story content - -**Why it works:** Gives you a "hero + problem + fix" structure that's perfect for authentic storytelling. Feels real, not salesy. - -**Use when:** The narrative is your strongest selling element. Great for UGC, testimonials, and personal brand content. - -**Structure:** -- **S - Situation:** Set the scene. Where were you/they? What was life like? -- **T - Task:** What needed to be done? What was the challenge? -- **A - Action:** What did you/they do? What was tried? -- **R - Result:** What happened? The outcome. -- **Solution:** Connect it to your product naturally. - -**Example (UGC Script):** -``` -[Situation] Last year I was working 80 hours a week and still drowning. -[Task] I needed to 10x my output without hiring a team. -[Action] I tested 47 different AI tools over 3 months. -[Result] Found one that literally cut my work in half. -[Solution] Now I use it daily. Here's my exact workflow. -``` - ---- - -### 13. G.R.A.B (Get Attention → Relate → Action → Benefit) - -**The thumb-stopper.** Built for the first 3 seconds. - -**Works well for:** -- TikTok and Reels -- YouTube Shorts -- Instagram Stories -- Any short-form video -- Feed ads -- Push notifications - -**Why it works:** Very fast emotional arc. Optimized for short attention spans and scroll culture. - -**Use when:** You have under 10 seconds to hook and convert. Speed is everything. - -**Structure:** -- **G - Get Attention:** Pattern interrupt. Bold statement. Visual hook. -- **R - Relate:** Quick connection to their reality. "If you're like me..." -- **A - Action:** What to do. -- **B - Benefit:** What they get. - -**Example:** -``` -[Get Attention] Stop scrolling. This saved my business. -[Relate] If you're tired of posting content that gets ignored... -[Action] Try this one hook format. -[Benefit] I went from 200 to 20,000 views in a week. -``` - ---- - -### 14. SLAP (Stop → Look → Act → Purchase) - -**The simplicity framework.** For high-volume, fast-twitch ads. - -**Works well for:** -- Feed ads at scale -- Retargeting -- Flash sales -- Limited time offers -- App install campaigns -- E-commerce promotions - -**Why it works:** Simple and fast. No complexity. Stop them, hook them, convert them. - -**Use when:** You're running high-volume ads that need speed and simplicity. Great for offers that don't need explanation. - -**Structure:** -- **S - Stop:** Pattern interrupt. Something unexpected. -- **L - Look:** Give them a reason to keep watching/reading. -- **A - Act:** Tell them what to do. -- **P - Purchase:** Make the buy easy and clear. - ---- - -## Quick Reference: Framework by Goal - -| Goal | Top Choices | Also Consider | -|------|-------------|---------------| -| Quick conversion | PAS, SLAP, G.R.A.B | AIDA, 4P | -| Build trust first | ACCA, QUEST, PASTOR | AIDA, 5-Point | -| Show transformation | BAB, STAR Story, 4P | PAS, AIDA | -| Highlight features | FAB, AIDA | PAS, 5-Point | -| Long-form selling | PASTOR, 5-Point, AIDA | PPPP, ACCA | -| Retargeting | QUEST, PAS, SLAP | AIDA, BAB | -| Education-heavy | ACCA, PASTOR, QUEST | AIDA, FAB | -| UGC/Influencer | STAR Story, PAS, G.R.A.B | BAB, AIDA | -| Storytelling | PASTOR, BAB, STAR Story | AIDA, PPPP | -| Product launch | AIDA, 5-Point, PAS | BAB, FAB | - ---- - -## Quick Reference: Framework by Platform - -| Platform | Top Choices | Also Consider | -|----------|-------------|---------------| -| Facebook Ads | AIDA, PAS, BAB | 5-Point, FAB | -| Instagram Ads | PAS, BAB, AIDA | G.R.A.B, FAB | -| TikTok | G.R.A.B, PAS, SLAP | BAB, STAR Story | -| YouTube (short) | AIDA, PAS, G.R.A.B | BAB | -| YouTube (long) | PASTOR, AIDA, 5-Point | ACCA | -| LinkedIn | AIDA, BAB, PAS | ACCA, FAB | -| Twitter/X | PAS, AIDA, G.R.A.B | BAB | -| Email | PAS, AIDA, QUEST | BAB, 5-Point | -| Landing Page | AIDA, PAS, BAB | PASTOR, 5-Point | -| Sales Page | PASTOR, AIDA, 5-Point | PAS, BAB | -| E-commerce | FAB, AIDA, PAS | BAB, 5-Point | - ---- - -## Choosing Between Frameworks - -**When multiple frameworks could work, consider:** - -1. **Audience awareness level** - - Unaware of problem → ACCA, AIDA - - Problem-aware → PAS, BAB - - Solution-aware → FAB, 5-Point - - Product-aware → SLAP, QUEST - -2. **Copy length available** - - < 50 words → G.R.A.B, SLAP, PAS - - 50-200 words → AIDA, PAS, BAB, FAB - - 200-500 words → AIDA, 5-Point, ACCA - - 500+ words → PASTOR, AIDA, PPPP - -3. **Primary angle** - - Pain-focused → PAS - - Transformation-focused → BAB - - Feature-focused → FAB - - Story-focused → PASTOR, STAR Story - - Proof-focused → 5-Point - -4. **Default choice when unsure: AIDA or PAS** - - AIDA if you need structure and flexibility - - PAS if the pain point is strong and clear - ---- diff --git a/ad-copy/references/direct-response-principles.md b/ad-copy/references/direct-response-principles.md deleted file mode 100644 index 6edc74a..0000000 --- a/ad-copy/references/direct-response-principles.md +++ /dev/null @@ -1,116 +0,0 @@ -# Direct Response Principles - -These are not suggestions. They're the physics of conversion copy. - -### Emotion First, Logic Second - -People buy on emotion and justify with logic. This has been true for 2,000 years (Cicero used it to win elections in 63 BC). Every piece of copy that moves people works on this principle — fear, hope, pride, frustration, relief. The product is never the subject. The emotion is. The product is the exit. - -Apply the sequence: make them feel something → then give them the rational justification to act. - -### Open Loops - -An open loop is an unresolved question in the reader's mind. The brain has physical discomfort with unresolved information (Zeigarnik Effect: incomplete tasks are remembered far better than completed ones). Open a loop early and delay closing it as long as possible. - -- "I spent $5k on XYZ and I hate what I found…" — reader can't stop until they know what was found -- "Here's what nobody tells you about picking stocks" — reader needs to see it before leaving -- Tease a result, reveal, or test in the hook — hold the payoff until the end - -**Rule:** Open a loop in the first line. Close it only in the CTA or final beat. - -### Curiosity Gap - -The space between what someone knows and what they want to know. Foreshadow the destination, withhold the route. - -- Movie shows the ending first, cuts to "72 hours earlier" — you watch for 2 hours because you know where it ends but not how -- In copy: state the outcome early ("how I 10x'd my research speed"), then build toward it — never give the answer before the middle - -Curiosity gap sustains attention between the open loop (tension) and the close (payoff). - ---- - -### AIDA (Attention → Interest → Desire → Action) - -Every piece of copy follows this arc. The mistake is spending 80% on Attention and 5% on Action. - -| Stage | Job | Example (Bloom) | -|-------|-----|-----------------| -| **Attention** | Stop the scroll. Pattern interrupt. | "Your portfolio dropped 4% today. Do you know why?" | -| **Interest** | Connect to their problem. Be specific. | "Most investors find out what moved their stocks 3 days late. From a CNBC headline." | -| **Desire** | Show the outcome. Make it tangible. | "Bloom gives you the exact catalyst, analyst rating changes, and insider trades. In real time." | -| **Action** | Tell them exactly what to do. One action. | "Download free. See your first stock breakdown in 60 seconds." | - -### PAS (Problem → Agitate → Solve) - -More aggressive than AIDA. Best for audiences that know they have a problem but haven't solved it yet. - -- **Problem**: Name it. Specifically. "You're checking 4 apps and 6 tabs to research one stock." -- **Agitate**: Make the pain vivid. "By the time you piece it all together, the move already happened. You're always a day late." -- **Solve**: Position your product as the obvious fix. "Bloom pulls everything into one screen. Analyst ratings, insider trades, earnings, catalysts. Research a stock in 30 seconds, not 30 minutes." - -### The Offer Stack - -What you get + bonuses + guarantee + urgency = irresistible offer. - -``` -WHAT YOU GET: -✓ AI-powered stock research (covers 6,000+ tickers) -✓ Real-time analyst rating changes -✓ Insider trading alerts -✓ Earnings breakdowns before and after - -BONUS: -✓ Watchlist with smart alerts (free tier) -✓ AI chat that actually cites sources - -GUARANTEE: -✓ Free to download. No credit card. Cancel anytime. - -URGENCY: -✓ "Premium is 50% off for the first 1,000 users this month" -``` - -Even for a free app download, stack the value. List everything they get. Make free feel like a steal. - -### Risk Reversal - -Remove every reason NOT to act. -- "Free to download" → removes cost objection -- "No credit card required" → removes commitment fear -- "Cancel anytime" → removes lock-in anxiety -- "Takes 30 seconds to set up" → removes time objection -- "Used by 50,000+ investors" → removes "is this legit?" doubt - -### Urgency and Scarcity - -Only use when real. Fake urgency destroys trust. - -- ✅ "Premium is 50% off through January" (real deadline) -- ✅ "Limited to first 1,000 users" (real cap) -- ✅ "Earnings season starts Monday. Set up alerts now." (real event) -- ❌ "Limited time offer!" (meaningless) -- ❌ "Don't miss out!" (says nothing) -- ❌ Countdown timers that reset on page refresh (fraud) - -### Specificity Sells - -The specific is more believable than the general. Always. - -| ❌ Generic | ✅ Specific | -|-----------|------------| -| "Powerful stock research" | "Research any stock in 30 seconds" | -| "AI-powered insights" | "AI that reads 10-K filings so you don't have to" | -| "Stay informed" | "Get alerts when analysts upgrade your stocks" | -| "Trusted by thousands" | "Used by 52,000 investors" | -| "Save time" | "Replace 6 tabs with 1 screen" | - -### Social Proof - -Types ranked by conversion impact: -1. **Specific numbers**: "52,000 investors use Bloom" > "thousands of users" -2. **Star ratings**: "4.8★ on the App Store (2,400+ ratings)" -3. **User quotes with specifics**: "I found a 40% undervalued stock in my first week" > "Great app!" -4. **Authority**: "Featured in TechCrunch, Product Hunt #1" -5. **Velocity**: "1,000 new users last week" (momentum > total) - ---- diff --git a/ad-copy/references/lead-magnet-patterns.md b/ad-copy/references/lead-magnet-patterns.md deleted file mode 100644 index abfa502..0000000 --- a/ad-copy/references/lead-magnet-patterns.md +++ /dev/null @@ -1,276 +0,0 @@ -# Lead Magnet Post Patterns - -This reference contains proven patterns for lead magnet giveaway posts that maximize comments and DM opt-ins. - -> **Note:** Opening hooks are generated using `viral-hook-creator` patterns. This file focuses on value anchors, CTAs, and post structure. - ---- - -## The Psychology - -Lead magnet posts work because they stack three psychological triggers: -1. **Viral hook** — Stops the scroll with curiosity (from viral-hook-creator) -2. **Value perception** — "This is worth real money" -3. **Low friction** — "All I have to do is comment" - -Miss any of these and engagement drops significantly. - ---- - -## Value Anchor Patterns - -Value anchors make the free offer feel valuable. Without them, people assume it's low quality. - -### Direct Price Anchors -- "Could easily charge $[X] for this." -- "This would cost $[X] from a consultant." -- "Worth at least $[X] based on what's inside." -- "Normally $[X]." - -### Scarcity/Urgency Anchors -- "Will charge $[X] for it in [Y] days." -- "Free for the next 48 hours." -- "Going behind a paywall next week." -- "First [X] people only." - -### Social Proof Anchors -- "[X] people have already grabbed this." -- "[X]+ downloads in the first week." -- "The same framework [notable person/company] uses." - -### Implicit Value Anchors -- "What I wish I had when I started..." -- "This took me [X] years to figure out..." -- "The exact [thing] I used to [achieve result]..." - ---- - -## CTA Patterns - -The CTA must be crystal clear and low friction. - -### Twitter/X CTAs -**Standard:** -``` -Comment "[WORD]" and I'll send it to you for free (must be following) -``` - -**With Like:** -``` -Like + Comment "[WORD]" and it's yours for free. - -(Must be following so I can DM you) -``` - -**With Repost:** -``` -Comment "[WORD]" and I'll DM you. - -Repost to help others find this. - -(Must be following) -``` - -### LinkedIn CTAs -**Standard:** -``` -1. Connect with me -2. Comment "[WORD]" - -I'll send it straight to your DMs. - -P.S. Repost for priority in the queue -``` - -**Alternative:** -``` -Want it? Here's how: - -1. Connect with me (so I can message you) -2. Comment "[WORD]" below - -I'll DM you the link. - -P.S. Repost this and I'll prioritize your DM -``` - ---- - -## Trigger Word Selection - -The trigger word should be: -- **Relevant** to the lead magnet (FRAMEWORK, CHECKLIST, TEMPLATE, GUIDE, etc.) -- **Memorable** and easy to type -- **Uppercase** for visibility - -### Common Trigger Words by Lead Magnet Type -- Framework → "FRAMEWORK" -- Checklist → "CHECKLIST" or "LIST" -- Template → "TEMPLATE" -- Course → "COURSE" or "FREE" -- Guide → "GUIDE" -- Playbook → "PLAYBOOK" -- Swipe file → "SWIPE" -- Tool/Software → "TOOL" or product name -- Blueprint → "BLUEPRINT" -- Custom/Specific → Use the product name (e.g., "SKILL") - ---- - -## Post Structures - -### Quick Format Structure -``` -[OPENING HOOK - from viral-hook-creator] - -[WHAT YOU BUILT] - -[VALUE ANCHOR] - -[CTA] -``` - -**Example:** -``` -I spent 3 months studying every #1 Product Hunt launch. - -Then I built a Claude Skill that gives you a personalized launch checklist based on YOUR product. - -Could easily charge $99 for this. - -Comment "SKILL" and I'll send it to you for free (must be following) -``` - -### Detailed Format Structure -``` -[OPENING HOOK - from viral-hook-creator] - -[WHAT YOU BUILT] - -Inside you'll find: - -→ [Benefit/content 1] -→ [Benefit/content 2] -→ [Benefit/content 3] -→ [Benefit/content 4] - -Want the full [playbook/framework/guide]? - -[CTA] -``` - -**Example:** -``` -I spent over 100+ hours researching the best prompts for Claude, Gemini and OpenAI. - -So I built a blueprint on how to prompt AI the right way. - -Inside you'll find: - -→ 100+ examples on how to actually prompt AI the right way -→ A guidebook on the best AI tools for specific tasks -→ Why traditional prompting won't cut it anymore -→ How to use the tools in sync - -Want the full playbook? - -Comment "FRAMEWORK" and I'll send it to you. - -(Must be following) -``` - ---- - -## High-Performing Examples - -### Example 1: SaaS Framework (Quick Format) -``` -My team & I have developed dozens of SaaS products that raised over 150M+ combined. - -So I've spent 73 hours packaging our learnings into this Framework. - -Will charge $199 for it in 7 days. - -Like + Comment "framework" and it's yours for free. - -(Must be following so I can DM you) -``` - -**Why it works:** -- Team credibility + specific achievement ($150M) -- Specific time investment (73 hours) -- Urgency anchor (7 days) -- Like + Comment increases engagement - -### Example 2: AI Prompting Guide (Detailed Format) -``` -I spent over 100+ hours researching the best prompts for Claude, Gemini and OpenAI. - -So I built a blueprint on how to prompt AI the right way. - -Inside you'll find: - -→ 100+ examples on how to actually prompt AI the right way -→ A guidebook on the best AI tools for specific tasks -→ Why traditional prompting won't cut it anymore -→ How to use the tools in sync - -Want the full playbook? - -Comment "FRAMEWORK" and I'll send it to you. - -(Must be following) -``` - -**Why it works:** -- Specific time investment (100+ hours) -- Clear deliverable (blueprint) -- 4 specific bullet points showing value -- Simple CTA - -### Example 3: Product Hunt Skill (Quick Format) -``` -I spent 3 months studying every #1 Product Hunt launch. - -Then I built a Claude Skill that gives you a personalized launch checklist based on YOUR product. - -Could easily charge $99 for this. - -Comment "SKILL" and I'll send it to you for free (must be following) -``` - -**Why it works:** -- Time investment with specific scope (every #1 launch) -- Personalization angle (based on YOUR product) -- Reasonable price anchor ($99) -- Direct CTA - ---- - -## Common Mistakes to Avoid - -1. **Weak opening hook** — Generic opener vs viral hook pattern with trigger words -2. **No value anchor** — Without price context, free feels worthless -3. **Vague bullets** — "Useful tips" vs "47 email subject lines that got 60%+ open rates" -4. **Complex CTA** — More than 2 steps kills conversion -5. **Wrong trigger word** — Generic words like "YES" or "ME" get lost in comments -6. **Missing "must be following"** — You can't DM non-followers on most platforms -7. **Too salesy** — Lead magnet posts should feel generous, not pushy - ---- - -## Platform-Specific Notes - -### Twitter/X -- Long-form posts work well -- "Must be following" is essential for DMs -- Repost requests can double reach -- Thread format can work for very detailed lead magnets - -### LinkedIn -- "Connect with me" is necessary (can't message non-connections) -- More professional tone, but still direct -- "Repost for priority" creates urgency -- Avoid hashtags in the main post body - ---- diff --git a/ad-copy/references/platform-character-limits-reference.md b/ad-copy/references/platform-character-limits-reference.md deleted file mode 100644 index 2336c22..0000000 --- a/ad-copy/references/platform-character-limits-reference.md +++ /dev/null @@ -1,74 +0,0 @@ -# Platform Character Limits Reference - -Memorize this. Every character counts in paid media. - -### Google Ads - -| Element | Character Limit | Notes | -|---------|----------------|-------| -| Headline | **30 characters** | 15 max per RSA | -| Long headline | **90 characters** | Performance Max | -| Description | **90 characters** | 4 max per RSA | -| Display URL path | **15 characters** each | 2 paths max | -| Callout extension | **25 characters** | | -| Sitelink title | **25 characters** | | -| Sitelink description | **35 characters** per line | 2 lines | -| Structured snippet value | **25 characters** | | - -### Meta/Facebook Ads - -| Element | Character Limit | Notes | -|---------|----------------|-------| -| Primary text | **125 characters** visible (2,200 max) | First 125 shown before "See More" | -| Headline | **40 characters** recommended (255 max) | Truncates on mobile around 40 | -| Link description | **30 characters** recommended (255 max) | Often hidden on mobile | -| Ad name (internal) | **255 characters** | Not shown to users | - -### TikTok Ads - -| Element | Character Limit | Notes | -|---------|----------------|-------| -| Ad text | **100 characters** recommended (999 max) | First 100 visible | -| Display name | **40 characters** | Brand name shown | -| CTA button | Platform presets only | "Download", "Learn More", "Shop Now" | -| Video | **5-60 seconds** | 15-30s optimal for conversion | - -### Apple App Store (iOS) - -| Element | Character Limit | Notes | -|---------|----------------|-------| -| App name | **30 characters** | Most important ranking factor | -| Subtitle | **30 characters** | Visible in search results | -| Keyword field | **100 characters** | Comma-separated, no spaces after commas | -| Promotional text | **170 characters** | Above description, can change anytime without review | -| Description | **4,000 characters** | Only first 3 lines visible before "more" | -| What's New | **4,000 characters** | Shown on update screen | -| Screenshots | **10 max** | First 3 visible in search (most critical) | - -### Google Play Store (Android) - -| Element | Character Limit | Notes | -|---------|----------------|-------| -| App name | **30 characters** | | -| Short description | **80 characters** | Visible in search results. This is your pitch. | -| Full description | **4,000 characters** | Keyword-indexed (unlike iOS description) | -| What's New | **500 characters** | | -| Screenshots | **8 max** | First 3-4 visible in search | - -### Push Notifications - -| Platform | Title Limit | Body Limit | Notes | -|----------|------------|------------|-------| -| iOS | **~50 characters** visible | **~150 characters** visible | Varies by device/lock screen | -| Android | **65 characters** | **240 characters** | Expanded notification shows more | -| Rich push (iOS) | Same | Same + image/buttons | Requires notification extension | - -### Email - -| Element | Guideline | Notes | -|---------|-----------|-------| -| Subject line | **30-50 characters** optimal | 50% open on mobile, shorter = better | -| Preview text | **40-90 characters** | Shows after subject on most clients | -| CTA button text | **2-5 words** | "Start Investing Free" not "Click Here to Get Started with Our Platform" | - ---- diff --git a/ad-copy/references/process-writing-copy-with-this-skill.md b/ad-copy/references/process-writing-copy-with-this-skill.md deleted file mode 100644 index f39af23..0000000 --- a/ad-copy/references/process-writing-copy-with-this-skill.md +++ /dev/null @@ -1,13 +0,0 @@ -# Process: Writing Copy with This Skill - -1. **Identify the format** (App Store, Google Ad, landing page, TikTok script, push, email) -2. **Read WRITING-STYLE.md** for tone calibration -3. **Identify the audience awareness level** (unaware, problem-aware, solution-aware) -4. **Pick the framework** (AIDA for most ads, PAS for pain-heavy audiences, Offer Stack for pricing pages) -5. **Write to the character limits** (reference the table above, write to fit) -6. **Apply the anti-pattern checklist** (feature listing? weak CTA? no social proof? fix it) -7. **Include social proof** (never ship copy without at least one proof element) -8. **Write 3 variants** for A/B testing (different hooks, same structure) -9. **Check against WRITING-STYLE.md** one more time (does it sound like Eric? Would he say this to a friend?) - ---- diff --git a/ad-copy/references/quick-reference-cta-library.md b/ad-copy/references/quick-reference-cta-library.md deleted file mode 100644 index a2c7d3f..0000000 --- a/ad-copy/references/quick-reference-cta-library.md +++ /dev/null @@ -1,18 +0,0 @@ -# Quick Reference: CTA Library - -Strong CTAs for Bloom, organized by context: - -| Context | CTA | Notes | -|---------|-----|-------| -| App Store | "Download Bloom Free" | Risk reversal built in | -| Google Ad | "Get Bloom — Free Download" | Action + risk reversal | -| Landing page (primary) | "Download Free" | Short, clear, no friction words | -| Landing page (secondary) | "See How It Works" | For not-ready visitors | -| TikTok/Meta | "Link in bio" / "Download now" | Platform native | -| Push notification | "See the analysis →" | Implies content waiting for them | -| Email (free user) | "Research Your Next Stock" | Activity-focused, not upgrade-focused | -| Email (upgrade) | "Get 50% Off Premium" | Specific offer | -| Email (win-back) | "See What You Missed" | Curiosity + FOMO | -| Trial expiring | "Keep Premium" | Loss aversion framing | - -**Never use:** "Learn More", "Click Here", "Submit", "Get Started", "Sign Up Now", "Explore" diff --git a/ad-copy/references/quiz-funnel-copy.md b/ad-copy/references/quiz-funnel-copy.md deleted file mode 100644 index 32ebe5a..0000000 --- a/ad-copy/references/quiz-funnel-copy.md +++ /dev/null @@ -1,67 +0,0 @@ -# Quiz Funnel Copy - -Source: @DTC_Quizbuilder (https://x.com/DTC_Quizbuilder/status/2010379560769015885) - -## When to Use - -When running paid ads to a subscription app and cold traffic conversion is below 2%. A quiz between the ad and the offer warms traffic through micro-commitments and belief-seeding. - -Funnel: Ad → Web Quiz (6-8 questions) → Captive Loading Screen → Personalized Results → App Store / Paywall - -## Quiz Question Copy Rules - -**Q1-Q2: Zero cognitive load.** Age range, gender, experience level. No thinking required. The goal is one click, not one insight. "How old are you?" beats "What's your biggest financial dream?" - -**Q3-Q4: Aspirational.** Now go emotional. "What's your #1 investing goal?" with options like "Build wealth for retirement", "Beat inflation", "Replace my income." These questions seed the desire before they see the product. - -**Q5-Q6: Pain points.** "What's been your biggest challenge with investing?" Options surface objections you'll handle on the results page: "I don't know what to buy", "I always buy at the wrong time", "Too much conflicting information." - -**Option copy:** 4 options max per question. Short (under 8 words each). Always include a catch-all ("None of the above" or "I'm not sure yet"). Decision fatigue kills completion. - -**Breather slides:** After Q4, insert a non-question slide with social proof: "Join 50,000+ investors who use AI to make smarter decisions." Resets cognitive load. Feels like progress. - -## Captive Loading Screen Copy - -The 10-15 seconds while "calculating results" is captive attention. The user can't click away. Use it. - -Show in sequence: -1. Strong testimonial with specific numbers ("Bloom helped me spot the Tesla dip 2 days before the rebound") -2. Social proof stat ("Trusted by X investors") -3. Product preview (screenshot of the app doing the thing they just said they want) - -## Results Page Copy - -The results page IS the sales page. Structure: - -1. **Personalized headline:** "Based on your answers, you're a [Growth-Focused / Conservative / AI-Curious] investor." Mirror their quiz answers back. -2. **Problem restate:** "You told us [pain point from Q5]. Here's why that happens." Use their exact answer. -3. **Solution frame:** "Bloom's AI analyzes [thing] so you don't have to [pain point]." -4. **Social proof:** Testimonial matching their investor type. -5. **CTA:** "Get Your Personalized Plan" → App Store link. - -## Retargeting Copy (Non-Completers) - -Everyone who quit the quiz or didn't convert gave you data. Write retargeting ads that match their last answer: - -| Quiz answer | Retargeting angle | -|-------------|-------------------| -| "I don't know what to invest in" | "Bloom tells you exactly what to buy and when" | -| "I always buy at the wrong time" | "AI that spots entry points before you read about them" | -| "Tried other apps, didn't help" | "Why Bloom's AI is different from [competitor]" | -| "Not enough time to research" | "2 minutes/day. That's all Bloom needs." | - -Specific beats generic. A retargeting ad that says "you told us you struggle with timing" converts better than "download our investing app." - -## Drop-Off Benchmarks - -- Q1: 30-40% drop-off (normal, biggest filter) -- Q2-Q8: Under 15% each -- Overall completion: 25%+ is good -- If any question has 10%+ drop-off: simplify options, reduce choices, add catch-all - -## Bloom-Specific Notes - -Bloom's onboarding already asks risk tolerance and goals post-install. A web quiz version of this flow could: -1. Warm cold traffic before the App Store page -2. Feed retargeting segments even for non-installers -3. Pre-frame the value prop based on the user's self-identified investor type diff --git a/ad-copy/references/real-world-examples-finance-investing-apps.md b/ad-copy/references/real-world-examples-finance-investing-apps.md deleted file mode 100644 index 807d884..0000000 --- a/ad-copy/references/real-world-examples-finance-investing-apps.md +++ /dev/null @@ -1,61 +0,0 @@ -# Real-World Examples (Finance/Investing Apps) - -### High-Converting App Store Descriptions - -**Robinhood** (what they do well): -- Name: `Robinhood: Investing for All` — clear positioning in the name -- First line: "Invest in stocks, options, and ETFs with Robinhood Financial. Buy and sell crypto with Robinhood Crypto." — immediately tells you what you can DO -- Social proof embedded: "Join over 10 million people" - -**Seeking Alpha** (what they do well): -- Name: `Seeking Alpha: Stock Market` — keyword-rich -- Key line: "What Wall Street Analysts & Financial Experts Are Saying About Your Stocks" — creates FOMO -- Specific value: "4,700+ stocks rated with Quant Rankings" - -**Morningstar** (what they do well): -- Authority positioning: "Independent. Trusted. Transparent." -- Specifics: "Track 620,000+ investments worldwide" - -**What they all share:** Specific numbers. Clear benefits in the first line. Social proof or authority signals. Action-oriented language. - -### High-Converting Google Ad Examples (Finance) - -**Wealthfront:** -``` -Headline: "Invest on Autopilot" -Description: "Set it and forget it. Automated investing with free financial planning. Get your first $5K managed free." -``` -Why it works: Benefit-led headline. Specific offer (first $5K free). Risk reversal (free). - -**Betterment:** -``` -Headline: "Investing Made Better" -Description: "Smart investing without the emotional decisions. Start with as little as $10. No minimum balance." -``` -Why it works: Addresses pain (emotional decisions). Low barrier ($10). Risk reversal (no minimum). - -### Bloom Ad Copy Examples - -**Google Search Ad (targeting "stock research app"):** -``` -Headline 1: AI Stock Research App (21) -Headline 2: Research Stocks in Seconds (26) -Headline 3: Free Download — Bloom (20) -Description 1: Search any stock, get an instant AI breakdown. Analyst ratings, insider trades, earnings — all in one app. (89) -Description 2: 52,000+ investors. 4.8★ rating. AI reads the filings so you don't have to. Download free, no credit card. (90) -``` - -**TikTok Ad (script summary):** -``` -[0-2s] Text: "The app that reads SEC filings for you" - Voice: "I stopped spending hours on stock research." -[2-7s] "I used to have 6 tabs open. Yahoo Finance, SEC.gov, Seeking Alpha..." -[7-15s] "Now I just search any stock in this app and it gives me everything. - Analyst ratings. Insider trades. Bull case. Bear case." - [Show app screen recording] -[15-20s] "4.8 stars, 50K+ investors." -[20-25s] "It's free. Link in bio." - Text: "Bloom — Download Free" -``` - ---- diff --git a/ad-copy/references/references.md b/ad-copy/references/references.md deleted file mode 100644 index ca88f9f..0000000 --- a/ad-copy/references/references.md +++ /dev/null @@ -1,7 +0,0 @@ -# References - -| File | Contents | -|------|----------| -| `references/copy_frameworks.md` | 14 proven copywriting frameworks (PAS, AIDA, BAB, FAB, ACCA, STAR, etc.) with detailed structures, selection matrix by platform/goal, and when-to-use guidance | -| `references/writing_styles.md` | Voice and tone rules from Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, Collier. Contains banned phrases list, AI tell patterns, and how human copy sounds. | -| `references/lead-magnet-patterns.md` | Lead magnet post structures, value framing techniques, CTA patterns for social giveaway posts | diff --git a/ad-copy/references/skill-integration.md b/ad-copy/references/skill-integration.md deleted file mode 100644 index 2609074..0000000 --- a/ad-copy/references/skill-integration.md +++ /dev/null @@ -1,7 +0,0 @@ -# Skill Integration - -- **Hooks skill** (`hooks/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). -- **Google Ads skill** (`google-ads/SKILL.md`): Use for campaign management, performance queries, and pausing underperformers. This skill writes the copy; that skill deploys and measures it. -- **Meta Ads skill** (`meta-ads/SKILL.md`): Use for creating/managing Meta ad creatives and measuring performance. - ---- diff --git a/ad-copy/references/test-app-store-screenshot-order.md b/ad-copy/references/test-app-store-screenshot-order.md deleted file mode 100644 index 66b1a2e..0000000 --- a/ad-copy/references/test-app-store-screenshot-order.md +++ /dev/null @@ -1,12 +0,0 @@ -# Test: App Store Screenshot Order - -- Date: 2026-01-15 to 2026-01-29 -- Variants: A (benefit text first) vs B (UI screenshot first) -- Sample: 12,000 impressions each -- Result: A won, 23% higher conversion rate -- Confidence: 97% -- Action: Implemented A as default -- Learning: Benefit text > raw UI for top-of-funnel discovery users -``` - ---- diff --git a/ad-copy/references/the-seven-sweeps-copy-editing-framework.md b/ad-copy/references/the-seven-sweeps-copy-editing-framework.md deleted file mode 100644 index 3796ba5..0000000 --- a/ad-copy/references/the-seven-sweeps-copy-editing-framework.md +++ /dev/null @@ -1,19 +0,0 @@ -# The Seven Sweeps (Copy Editing Framework) - -After drafting any copy, run these seven sequential editing passes. Each focuses on one dimension. - -1. **Clarity**: Can the reader understand what you're saying? Cut confusing sentences, unclear pronouns, jargon, ambiguity. -2. **Voice & Tone**: Consistent brand voice throughout? Check for shifts between casual and corporate. Read aloud for inconsistencies. -3. **So What**: Does every claim answer "why should I care?" For every feature statement, add the "which means..." bridge to a benefit. -4. **Prove It**: Is every claim supported? Flag unsubstantiated assertions. Add testimonials, stats, case studies, or soften the claim. -5. **Specificity**: Replace vague with concrete. "Save time" → "Save 4 hours every week." "Many customers" → "2,847 teams." Remove anything that can't be made specific (it's filler). -6. **Heightened Emotion**: Does the copy make the reader feel something? Paint the "before" state vividly. Reference shared experiences. -7. **Zero Risk**: Have we removed every barrier to action? Address objections near CTAs. Add trust signals, guarantees, clear next steps. - -After each sweep, loop back to verify previous sweeps aren't compromised. The process is iterative. - -### Quick Word-Level Fixes -**Cut:** very, really, extremely, just, actually, basically, "in order to" -**Replace:** utilize → use, implement → set up, leverage → use, facilitate → help, innovative → new, robust → strong, seamless → smooth - ---- diff --git a/content-strategy/SKILL.md b/content-strategy/SKILL.md index d7f7cfe..b208c42 100644 --- a/content-strategy/SKILL.md +++ b/content-strategy/SKILL.md @@ -86,7 +86,7 @@ Write all three, then pick the right one for the format: - **Visual** — what they SEE in the first frame - **Audio** — what they HEAR in the first 3 seconds -> **Load on-demand:** `headlines` skill has 15+ proven hook formulas. +> **Load on-demand:** `hooks` skill has 15+ proven hook formulas. ### Hook Psychology Triggers @@ -290,7 +290,7 @@ Don't write here. Route to the right skill. | Tweets / X posts | `tweet-ideas` | | Articles / long-form | `article-writer` | | TikTok slideshows | `slideshow-creator` | -| Hooks and headlines | `headlines` | +| Hooks and headlines | `hooks` | | Ad copy (paid) | `copywriting` | | Paid creative concepts | `copywriting` (includes A/B blitz protocol) | | AI character video scripts | Write inline using Step 2c above | @@ -389,10 +389,6 @@ Retired pillars aren't deleted. Keep `tiktok-marketing/pillar-bench.json` and re | Reference | Contents | |-----------|---------| -| `references/6-elements-framework.md` | Paid creative element guidance (Media, Primary Text, Headline, etc.) | -| `references/ad-formats-library.md` | All formats with templates and examples | -| `references/copywriting-formulas.md` | PAS, AIDA, hooks, headlines | -| `references/creative-research-methods.md` | Research process and sources | | `references/analytics-loop.md` | Per-post tracking, pillar-level monthly review | | `references/feedback-loop.md` | Daily diagnostic, hook evolution, CTA rotation | | `references/calendar-batching.md` | Scheduling strategy, queue management, posting cadence | @@ -526,7 +522,7 @@ Source: @DTC_Quizbuilder thread (https://x.com/DTC_Quizbuilder/status/2010379560 ## Related Skills -- `headlines` — hook formulas and title generation +- `hooks` — hook formulas and title generation - `copywriting` — page copy, direct response, brand voice, A/B testing blitz - `tweet-ideas` — standalone tweet content - `article-writer` — long-form drafts diff --git a/copywriting/references/7-ugc-script-templates.md b/copywriting/references/7-ugc-script-templates.md index 6e713d8..f2c142b 100644 --- a/copywriting/references/7-ugc-script-templates.md +++ b/copywriting/references/7-ugc-script-templates.md @@ -1,10 +1,10 @@ # 7. UGC Script Templates (AI-Generated Video) -Script structures for AI-generated UGC testimonials. These pair with the Sora product integration pipeline (`sora/references/ugc-product-integration.md`) for full video production. +Script structures for AI-generated UGC testimonials. ## AI UGC Production Stack -Before scripting, build the production infrastructure. See `whop-content-rewards` skill for full detail. Summary: +Before scripting, build the production infrastructure. Summary: **1. Find a reference ad first** - Use [Meta Ad Library](https://facebook.com/ads/library) or [GetHooked.ai](https://gethooked.ai) — find ads in your category running 30+ days (run duration = proof of return) diff --git a/copywriting/references/lead-magnet-patterns.md b/copywriting/references/lead-magnet-patterns.md index abfa502..2d8bf3b 100644 --- a/copywriting/references/lead-magnet-patterns.md +++ b/copywriting/references/lead-magnet-patterns.md @@ -2,14 +2,14 @@ This reference contains proven patterns for lead magnet giveaway posts that maximize comments and DM opt-ins. -> **Note:** Opening hooks are generated using `viral-hook-creator` patterns. This file focuses on value anchors, CTAs, and post structure. +> **Note:** Opening hooks are generated using the `hooks` skill. This file focuses on value anchors, CTAs, and post structure. --- ## The Psychology Lead magnet posts work because they stack three psychological triggers: -1. **Viral hook** — Stops the scroll with curiosity (from viral-hook-creator) +1. **Viral hook** — Stops the scroll with curiosity (from `hooks` skill) 2. **Value perception** — "This is worth real money" 3. **Low friction** — "All I have to do is comment" @@ -121,7 +121,7 @@ The trigger word should be: ### Quick Format Structure ``` -[OPENING HOOK - from viral-hook-creator] +[OPENING HOOK - from hooks skill] [WHAT YOU BUILT] @@ -143,7 +143,7 @@ Comment "SKILL" and I'll send it to you for free (must be following) ### Detailed Format Structure ``` -[OPENING HOOK - from viral-hook-creator] +[OPENING HOOK - from hooks skill] [WHAT YOU BUILT] diff --git a/copywriting/references/references.md b/copywriting/references/references.md index d515deb..209474d 100644 --- a/copywriting/references/references.md +++ b/copywriting/references/references.md @@ -3,5 +3,5 @@ | File | Contents | |------|----------| | `references/copy-frameworks.md` | 14 proven copywriting frameworks (PAS, AIDA, BAB, FAB, ACCA, STAR, etc.) with detailed structures, selection matrix by platform/goal, and when-to-use guidance | -| `references/writing_styles.md` | Voice and tone rules from Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, Collier. Contains banned phrases list, AI tell patterns, and how human copy sounds. | +| `references/writing-styles.md` | Voice and tone rules from Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, Collier. Contains banned phrases list, AI tell patterns, and how human copy sounds. | | `references/lead-magnet-patterns.md` | Lead magnet post structures, value framing techniques, CTA patterns for social giveaway posts | diff --git a/copywriting/references/skill-integration.md b/copywriting/references/skill-integration.md index 37aff39..1cafc63 100644 --- a/copywriting/references/skill-integration.md +++ b/copywriting/references/skill-integration.md @@ -1,7 +1,6 @@ # Skill Integration -- **Headlines skill** (`hooks/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). -- **Google Ads skill** (`google-ads/SKILL.md`): Use for campaign management, performance queries, and pausing underperformers. This skill writes the copy; that skill deploys and measures it. +- **Hooks skill** (`hooks/SKILL.md`): Use hook formulas for ad headlines, TikTok hooks, email subject lines. The layered hook system applies to landing pages (hero → subhead → body → CTA). - **Meta Ads skill** (`meta-ads/SKILL.md`): Use for creating/managing Meta ad creatives and measuring performance. --- diff --git a/ad-copy/references/writing_styles.md b/copywriting/references/writing-styles.md similarity index 100% rename from ad-copy/references/writing_styles.md rename to copywriting/references/writing-styles.md diff --git a/copywriting/references/writing_styles.md b/copywriting/references/writing_styles.md deleted file mode 100644 index 5850f50..0000000 --- a/copywriting/references/writing_styles.md +++ /dev/null @@ -1,233 +0,0 @@ -# Writing Styles & Voice Reference - -How to write copy that sounds like a human wrote it. Built from the principles of Ogilvy, Schwartz, Hopkins, Halbert, Sugarman, Caples, and Collier. - ---- - -## The One Rule That Overrides Everything - -Write like you're talking to one person. Not an audience. One person. The specific person who has the specific problem your product solves. Read every sentence back as if you're saying it out loud to them across a table. - ---- - -## The Legendary Principles - -### Ogilvy: Show, Don't Explain - -"At 60 miles an hour, the loudest noise in this new Rolls-Royce comes from the electric clock." - -He never said "this car is quiet." He showed it through a single detail that made the reader feel the quietness. This is the single most important lesson in copywriting. - -**What this means in practice:** -- Don't say "high quality." Show what high quality looks like in a specific, concrete detail. -- Don't say "easy to use." Describe someone using it in a way that feels effortless. -- Don't say "customers love it." Quote one customer saying one specific thing that only someone who actually used it would say. -- The reader should arrive at your conclusion themselves. Your job is to arrange the details so that conclusion is obvious. - -**Examples:** -- BAD: "Our supplement is made with premium, high-quality ingredients." -- GOOD: "We source our omega-3s from wild-caught mackerel off the coast of Peru. Not farmed. Not blended." - -- BAD: "Our app is incredibly intuitive and easy to use." -- GOOD: "My 67-year-old mother set it up herself. Took her 4 minutes. She texted me a screenshot." - -### Schwartz: Match the Message to Where They Actually Are - -Eugene Schwartz defined 5 levels of awareness. Most copy fails because it writes to someone at the wrong stage. - -| Level | Where they are | What your copy should do | -|-------|----------------|--------------------------| -| Unaware | Don't know they have a problem | Name the problem in a way that makes them go "wait, that's me" | -| Problem-aware | Know they have a problem, don't know solutions exist | Validate the problem. Make them feel less alone. | -| Solution-aware | Know solutions exist, haven't picked one | Show why your solution is different from what they've tried | -| Product-aware | Know your product exists, aren't sure it's for them | Remove objections. Show proof. Make the decision easy. | -| Most aware | Ready to buy, just need the final nudge | Make the CTA frictionless. Remove the last excuse. | - -**Why this matters:** If someone is Problem-Aware and your copy leads with features and specs, they leave immediately. If someone is Most-Aware and your copy starts from scratch explaining the problem, they feel like you're wasting their time. - -### Hopkins: Advertising Is Salesmanship in Print - -Claude C. Hopkins wrote "Scientific Advertising" in 1923. Still relevant. - -His core rules: -- **Lead with "reason why."** Don't just claim something. Explain the mechanism. People are skeptical by default. Give them a reason to believe. -- **Be specific.** "Saves you time" is meaningless. "Saved our users 2.4 hours on average in the first week" is a claim. Specificity = credibility. -- **Test everything.** Assume your first instinct is wrong. Write two versions. The data decides. -- **Speak to the individual.** "Dear Reader" energy, not "Dear Customer" energy. - -### Halbert: The Starving Crowd - -Gary Halbert's golden rule: find the hungry crowd first, then write to them. - -What this means for copy: -- The best copy in the world falls flat if no one who reads it actually has the problem. -- Before writing a single word, ask: who is already desperate for this? What are they already googling at 2am? Write to that moment. -- **Write to one person.** Imagine the single most frustrated version of your customer. Write to them specifically. The copy that works for them works for everyone. - -### Sugarman: The Slippery Slide - -Joseph Sugarman's principle: every element of your copy should pull the reader to the next one. No friction. No stopping points. The headline pulls them to the first sentence. The first sentence pulls them to the second. And so on until they hit the CTA having already said yes in their head. - -**How to apply it:** -- The first sentence of your copy should be the easiest sentence in the world to read. Short. Punchy. Impossible to stop at. -- Don't put a wall of text after your hook. Put one short sentence. -- Each paragraph earns the next one. If a paragraph doesn't pull the reader forward, cut it. -- The CTA should feel like the obvious next step, not a demand. - -### Caples: Headlines Do 80% of the Work - -John Caples tested thousands of headlines. His findings: -- Most people read headlines only. If your headline doesn't hook them, the body copy doesn't exist. -- The strongest headlines create a curiosity gap or a specific promise with a timeframe. -- Odd numbers outperform even numbers. Specific numbers outperform round ones. -- Headlines that self-select ("If you hate Mondays...") outperform broad ones. - -### Collier: Enter the Conversation Already Happening - -Robert Collier's rule: don't start a new conversation. Join the one already happening in your reader's head. - -**In practice:** -- Figure out what they're already thinking about when they see your ad. -- Start your copy from that exact thought. -- If a founder is already frustrated about their team missing deadlines, your first line should reference missed deadlines, not "project management." - ---- - -## AI Tells: The Banned List - -These are patterns that make copy sound like a machine wrote it. Every single one of these kills trust instantly. If you catch yourself writing any of these, stop and rewrite. - -### Banned Phrases (Never Use) -- "And honestly?" -- "It's not X. It's Y." / "This isn't about X. It's about Y." -- "The truth is..." -- "Here's the thing..." -- "At the end of the day..." -- "In today's fast-paced world..." -- "Game-changer" / "game-changing" -- "Let's dive in" / "Let's dive into" -- "Whether you're a X or a Y..." -- "Unlock your potential" -- "Take it to the next level" -- "Seamless experience" -- "Leverage your assets" -- "Streamline your workflow" -- "Revolutionize" -- "Robust" -- "Delve" -- "Empowering" -- "Tailored solutions" -- "Drive results" -- "Synergy" - -### Banned Punctuation Habits -- Em dashes used for dramatic effect. ("Write great copy — or don't bother trying.") Use a period or restructure the sentence instead. -- Multiple exclamation marks. -- Ellipses for fake suspense ("But wait...") - -### Banned Structural Patterns -- Starting a paragraph with "Now," as a transition word. -- Writing three short fragments in a row for "punch." (One fragment for emphasis is fine. Three in a row is a tic.) -- Ending a section with a one-liner that restates what you just said. ("That's how you win.") -- Fake vulnerability openers that are actually humble bragging. ("I almost quit. But I'm glad I didn't, because now I do $50K/month.") -- Listing benefits as a bulleted wall. Three bullets max. If you have more, weave them into sentences. - -### The Em Dash Rule -Em dashes have one job: a brief aside that adds a detail. Use them sparingly, at most once per paragraph. Never use them to build drama. Never use them twice in the same sentence. - -WRONG: "This tool — unlike anything else on the market — will completely change — the way you work." -RIGHT: "This tool will completely change the way you work. Nothing else comes close." - ---- - -## What Human Copy Actually Sounds Like - -### Use Contractions -"You are going to love this" sounds corporate. "You're going to love this" sounds like a person. - -### Use Fragments. Intentionally. -"Best part? It's free." This is a fragment. It works because it feels like speech. - -### Use "I" and "You" Freely -Good copy is a conversation between two people. "I" and "You" should appear in almost every paragraph. - -### Have Opinions -"Most project management tools are bloated garbage." This is an opinion. It's also a hook. Bland copy has no opinions. Good copy has strong ones. - -### Admit Limitations -"This won't work if you need X." Saying what your product can't do builds more trust than pretending it does everything. The reader respects honesty and stops being skeptical. - -### Use Sensory and Specific Details -"The dashboard loads in 0.8 seconds" is specific. "Lightning fast" is meaningless. Specificity is the fastest way to sound credible and human at the same time. - -### Revenue and Number Transparency -Sharing real numbers makes copy feel authentic. "$45,000/month in revenue" is a real claim. "Six figures" is vague and suspicious. - ---- - -## How to Structure Sentences That Sell - -### Short First. Long Second. -Open with a short sentence. Follow with a longer one that explains. This is how humans actually talk. - -GOOD: -"I wasted 6 months building the wrong product. I had a great idea, a solid team, and zero customers by the end." - -BAD: -"After spending approximately six months developing what I believed to be an innovative solution, I found myself confronted with the uncomfortable reality of having attracted zero customer interest." - -### Vary Your Sentence Length -Read your copy out loud. If every sentence is the same length, it sounds like a robot. Mix short punchy ones with longer ones that build. - -### The Specific Detail Over the Adjective -INSTEAD OF: "incredibly effective marketing strategy" -WRITE: "the marketing strategy that brought in 340 leads in 11 days" - -INSTEAD OF: "a user-friendly interface" -WRITE: "the whole thing fits on one screen. No menus, no dropdowns." - ---- - -## CTAs That Actually Work - -Don't say: "Sign Up" / "Submit" / "Learn More" / "Click Here" - -Say what happens when they click: -- "Get the free template" -- "See my first 30 days" -- "Start your free trial" -- "Download the guide" -- "Book a 15-minute call" - -Add a friction reducer after the CTA: -- "No credit card needed." -- "Takes 2 minutes to set up." -- "Cancel anytime." -- "See results in 14 days or your money back." - ---- - -## Testimonial Format That Works - -A testimonial with structure converts. A vague one doesn't. - -WEAK: "Great product, highly recommend!" - -STRONG FORMAT: [Before state] + [Specific action taken] + [Specific result] + [Timeframe] + [Emotion or implication] - -STRONG: "I was getting 12 leads a month from cold outreach. Started using the new templates on a Tuesday. By Friday I had 4 booked calls. Didn't change anything else." - ---- - -## Quick Sanity Check Before Finalizing - -Read the copy out loud. If any of these are true, rewrite: -- You stumbled over a sentence (it's too complicated) -- You felt bored halfway through (it's not pulling you forward — Sugarman's slippery slide is broken) -- You heard any of the Banned Phrases -- You saw an em dash used for drama -- You couldn't find a single opinion or specific number -- It could have been written about any product (it's not specific enough) -- It sounds like it was written by someone trying to sound smart (it wasn't written to sell) - ---- diff --git a/evaluate-content/SKILL.md b/evaluate-content/SKILL.md index a550a44..2e227c5 100644 --- a/evaluate-content/SKILL.md +++ b/evaluate-content/SKILL.md @@ -145,7 +145,7 @@ TRIM: [paragraph/sentence] → [shorter version] - **The reader** in one sentence: "A 28-year-old PM who just got assigned to an AI product and has no idea what evals are." - **Their trigger**: What happened that made them need this? "Their AI shipped a wrong answer and the CEO noticed." - **What they'd Google**: The search query that would lead to this. "how to test AI product quality" -- **Their awareness level** (from headlines skill): +- **Their awareness level** (from hooks skill): - Unaware: doesn't know the problem exists - Problem-aware: knows the problem, doesn't know the solution - Solution-aware: knows solutions exist, comparing options @@ -648,6 +648,6 @@ Use all three levels together. A great post (high individual score) in a dying p - Used by **article-writer** (revision pass) - Used by **typefully** (hook quality check) - Used by **tweet-ideas** (tweet quality) -- Used by **headlines** (title evaluation) +- Used by **hooks** (title evaluation) - Shares voice standards with **article-writer** humanizer section - **`~/marketing/WRITING-STYLE.md`** — ground truth for voice evaluation. Read the Kill Phrases list and Voice Fingerprint section before scoring Question 3. Generic "sounds human" is not the bar; Eric's specific fingerprint is. diff --git a/growth/references/psychology-models.md b/growth/references/psychology-models.md index 0414668..92f874b 100644 --- a/growth/references/psychology-models.md +++ b/growth/references/psychology-models.md @@ -12,7 +12,7 @@ You are an expert in applying psychological principles and mental models to mark ## How to Use This Skill **Check for product marketing context first:** -Check `~/clawd/SOUL.md` and `~/clawd/USER.md` for product and audience context before applying mental models. +Check `.agents/product-marketing-context.md` for product and audience context before applying mental models. Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users: diff --git a/meta-ads/SKILL.md b/meta-ads/SKILL.md index 638e704..adc30ee 100644 --- a/meta-ads/SKILL.md +++ b/meta-ads/SKILL.md @@ -12,7 +12,7 @@ Daily 4am routine: audit running ads via Meta Marketing API, kill underperformer ## API Credentials ```bash -TOKEN=$FACEBOOK_ACCESS_TOKEN # Meta Marketing API token +TOKEN=$META_ACCESS_TOKEN # Meta Marketing API token ACCOUNT="$BLOOM_AD_ACCOUNT_ID" # Bloom ad account (act_...) API="https://graph.facebook.com/v22.0" PAGE_ID="$BLOOM_PAGE_ID" # Facebook Page ID @@ -342,7 +342,7 @@ For iOS app campaigns, use Apple Custom Product Pages (CPPs) as the ad destinati ## Common Mistakes -1. **Token not set** — always use `$FACEBOOK_ACCESS_TOKEN` from env. Never hardcode. +1. **Token not set** — always use `$META_ACCESS_TOKEN` from env. Never hardcode. 2. **Wrong budget units** — daily_budget is in cents. $5/day = 500, $6/day = 600. 3. **Repeating a hook/format/concept combo** — always audit exclusion list first. 4. **Forgetting Android ad set** — each creative should get two ads (iOS + Android ad sets). diff --git a/paid-ads/SKILL.md b/paid-ads/SKILL.md index a111599..268b849 100644 --- a/paid-ads/SKILL.md +++ b/paid-ads/SKILL.md @@ -1,6 +1,6 @@ --- name: paid-ads -description: "When the user wants help with paid advertising campaigns on Google Ads, Meta, LinkedIn, Twitter/X, or other platforms. Use when someone mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'Google Ads,' 'Facebook ads,' 'ad budget,' or 'should I run ads.' For Meta API operations, see meta-ads. For Google Ads API, see google-ads." +description: "When the user wants help with paid advertising campaigns on Google Ads, Meta, LinkedIn, Twitter/X, or other platforms. Use when someone mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'Google Ads,' 'Facebook ads,' 'ad budget,' or 'should I run ads.' For Meta API operations, see meta-ads. " metadata: version: 1.0.0 --- diff --git a/seo-research/references/programmatic-seo.md b/seo-research/references/programmatic-seo.md index 90e8736..a460d34 100644 --- a/seo-research/references/programmatic-seo.md +++ b/seo-research/references/programmatic-seo.md @@ -12,7 +12,7 @@ You are an expert in programmatic SEO—building SEO-optimized pages at scale us ## Initial Assessment **Check for product marketing context first:** -Check `~/clawd/USER.md` for product context before proceeding. +Check `.agents/product-marketing-context.md` for product context before proceeding. Before designing a programmatic SEO strategy, understand: From db320d47fe3af4ab08cadf9f904bdb94ff52ff62 Mon Sep 17 00:00:00 2001 From: testuser Date: Tue, 31 Mar 2026 15:11:14 -0400 Subject: [PATCH 06/18] feat: add impeccable v2 command suite (21 commands) - Add all 21 command skills under impeccable/commands/ - New commands: /typeset, /arrange, /overdrive - Updated: /critique (Nielsen heuristics + personas + cognitive load), /audit (P0-P3 severity scoring), /frontend-design (latest refs) - Includes full reference files for critique, frontend-design - Synced from pbakaus/impeccable latest --- impeccable/SKILL.md | 9 +- impeccable/commands/adapt/SKILL.md | 198 ++++++++++ impeccable/commands/animate/SKILL.md | 174 +++++++++ impeccable/commands/arrange/SKILL.md | 124 ++++++ impeccable/commands/audit/SKILL.md | 147 ++++++++ impeccable/commands/bolder/SKILL.md | 116 ++++++ impeccable/commands/clarify/SKILL.md | 182 +++++++++ impeccable/commands/colorize/SKILL.md | 142 +++++++ impeccable/commands/critique/SKILL.md | 201 ++++++++++ .../critique/reference/cognitive-load.md | 106 ++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++ .../commands/critique/reference/personas.md | 178 +++++++++ impeccable/commands/delight/SKILL.md | 303 +++++++++++++++ impeccable/commands/distill/SKILL.md | 121 ++++++ impeccable/commands/extract/SKILL.md | 91 +++++ impeccable/commands/frontend-design/SKILL.md | 147 ++++++++ .../reference/color-and-contrast.md | 132 +++++++ .../reference/interaction-design.md | 195 ++++++++++ .../reference/motion-design.md | 99 +++++ .../reference/responsive-design.md | 114 ++++++ .../reference/spatial-design.md | 100 +++++ .../frontend-design/reference/typography.md | 133 +++++++ .../frontend-design/reference/ux-writing.md | 107 ++++++ impeccable/commands/harden/SKILL.md | 354 ++++++++++++++++++ impeccable/commands/normalize/SKILL.md | 70 ++++ impeccable/commands/onboard/SKILL.md | 245 ++++++++++++ impeccable/commands/optimize/SKILL.md | 265 +++++++++++++ impeccable/commands/overdrive/SKILL.md | 141 +++++++ impeccable/commands/polish/SKILL.md | 202 ++++++++++ impeccable/commands/quieter/SKILL.md | 102 +++++ impeccable/commands/teach-impeccable/SKILL.md | 71 ++++ impeccable/commands/typeset/SKILL.md | 115 ++++++ 32 files changed, 4915 insertions(+), 3 deletions(-) create mode 100644 impeccable/commands/adapt/SKILL.md create mode 100644 impeccable/commands/animate/SKILL.md create mode 100644 impeccable/commands/arrange/SKILL.md create mode 100644 impeccable/commands/audit/SKILL.md create mode 100644 impeccable/commands/bolder/SKILL.md create mode 100644 impeccable/commands/clarify/SKILL.md create mode 100644 impeccable/commands/colorize/SKILL.md create mode 100644 impeccable/commands/critique/SKILL.md create mode 100644 impeccable/commands/critique/reference/cognitive-load.md create mode 100644 impeccable/commands/critique/reference/heuristics-scoring.md create mode 100644 impeccable/commands/critique/reference/personas.md create mode 100644 impeccable/commands/delight/SKILL.md create mode 100644 impeccable/commands/distill/SKILL.md create mode 100644 impeccable/commands/extract/SKILL.md create mode 100644 impeccable/commands/frontend-design/SKILL.md create mode 100644 impeccable/commands/frontend-design/reference/color-and-contrast.md create mode 100644 impeccable/commands/frontend-design/reference/interaction-design.md create mode 100644 impeccable/commands/frontend-design/reference/motion-design.md create mode 100644 impeccable/commands/frontend-design/reference/responsive-design.md create mode 100644 impeccable/commands/frontend-design/reference/spatial-design.md create mode 100644 impeccable/commands/frontend-design/reference/typography.md create mode 100644 impeccable/commands/frontend-design/reference/ux-writing.md create mode 100644 impeccable/commands/harden/SKILL.md create mode 100644 impeccable/commands/normalize/SKILL.md create mode 100644 impeccable/commands/onboard/SKILL.md create mode 100644 impeccable/commands/optimize/SKILL.md create mode 100644 impeccable/commands/overdrive/SKILL.md create mode 100644 impeccable/commands/polish/SKILL.md create mode 100644 impeccable/commands/quieter/SKILL.md create mode 100644 impeccable/commands/teach-impeccable/SKILL.md create mode 100644 impeccable/commands/typeset/SKILL.md diff --git a/impeccable/SKILL.md b/impeccable/SKILL.md index b72fffe..1b42ed3 100644 --- a/impeccable/SKILL.md +++ b/impeccable/SKILL.md @@ -19,13 +19,13 @@ Design quality layer for Claude Code. 17 commands that audit, review, polish, an - Targeted fixes: `/colorize`, `/animate`, `/bolder`, `/quieter` - Design system alignment: `/normalize`, `/extract` -## 17 Commands +## 21 Commands | Command | What it does | |---|---| | `/teach-impeccable` | One-time setup: gather design context, save to project config | -| `/audit` | Technical quality checks (a11y, performance, responsive) | -| `/critique` | UX design review: hierarchy, clarity, emotional resonance | +| `/audit` | Technical quality checks (a11y, performance, responsive) — scores 5 dimensions with P0-P3 severity | +| `/critique` | UX design review — scores against Nielsen's 10 heuristics, persona archetypes, cognitive load | | `/normalize` | Align with design system standards | | `/polish` | Final pass before shipping | | `/distill` | Strip to essence — remove unnecessary complexity | @@ -40,6 +40,9 @@ Design quality layer for Claude Code. 17 commands that audit, review, polish, an | `/extract` | Pull into reusable components | | `/adapt` | Adapt for different devices | | `/onboard` | Design onboarding flows | +| `/typeset` | Fix typography: font choices, hierarchy, sizing, weight, readability | +| `/arrange` | Fix layout, spacing, visual rhythm, monotonous grids | +| `/overdrive` | Technically extraordinary effects: shaders, spring physics, scroll-driven reveals (beta) | ## 7 Reference Files diff --git a/impeccable/commands/adapt/SKILL.md b/impeccable/commands/adapt/SKILL.md new file mode 100644 index 0000000..165c66d --- /dev/null +++ b/impeccable/commands/adapt/SKILL.md @@ -0,0 +1,198 @@ +--- +name: adapt +description: Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility. +user-invocable: true +argument-hint: "[target] [context (mobile, tablet, print...)]" +--- + +Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. + +--- + +## Assess Adaptation Challenge + +Understand what needs adaptation and why: + +1. **Identify the source context**: + - What was it designed for originally? (Desktop web? Mobile app?) + - What assumptions were made? (Large screen? Mouse input? Fast connection?) + - What works well in current context? + +2. **Understand target context**: + - **Device**: Mobile, tablet, desktop, TV, watch, print? + - **Input method**: Touch, mouse, keyboard, voice, gamepad? + - **Screen constraints**: Size, resolution, orientation? + - **Connection**: Fast wifi, slow 3G, offline? + - **Usage context**: On-the-go vs desk, quick glance vs focused reading? + - **User expectations**: What do users expect on this platform? + +3. **Identify adaptation challenges**: + - What won't fit? (Content, navigation, features) + - What won't work? (Hover states on touch, tiny touch targets) + - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop) + +**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context. + +## Plan Adaptation Strategy + +Create context-appropriate strategy: + +### Mobile Adaptation (Desktop → Mobile) + +**Layout Strategy**: +- Single column instead of multi-column +- Vertical stacking instead of side-by-side +- Full-width components instead of fixed widths +- Bottom navigation instead of top/side navigation + +**Interaction Strategy**: +- Touch targets 44x44px minimum (not hover-dependent) +- Swipe gestures where appropriate (lists, carousels) +- Bottom sheets instead of dropdowns +- Thumbs-first design (controls within thumb reach) +- Larger tap areas with more spacing + +**Content Strategy**: +- Progressive disclosure (don't show everything at once) +- Prioritize primary content (secondary content in tabs/accordions) +- Shorter text (more concise) +- Larger text (16px minimum) + +**Navigation Strategy**: +- Hamburger menu or bottom navigation +- Reduce navigation complexity +- Sticky headers for context +- Back button in navigation flow + +### Tablet Adaptation (Hybrid Approach) + +**Layout Strategy**: +- Two-column layouts (not single or three-column) +- Side panels for secondary content +- Master-detail views (list + detail) +- Adaptive based on orientation (portrait vs landscape) + +**Interaction Strategy**: +- Support both touch and pointer +- Touch targets 44x44px but allow denser layouts than phone +- Side navigation drawers +- Multi-column forms where appropriate + +### Desktop Adaptation (Mobile → Desktop) + +**Layout Strategy**: +- Multi-column layouts (use horizontal space) +- Side navigation always visible +- Multiple information panels simultaneously +- Fixed widths with max-width constraints (don't stretch to 4K) + +**Interaction Strategy**: +- Hover states for additional information +- Keyboard shortcuts +- Right-click context menus +- Drag and drop where helpful +- Multi-select with Shift/Cmd + +**Content Strategy**: +- Show more information upfront (less progressive disclosure) +- Data tables with many columns +- Richer visualizations +- More detailed descriptions + +### Print Adaptation (Screen → Print) + +**Layout Strategy**: +- Page breaks at logical points +- Remove navigation, footer, interactive elements +- Black and white (or limited color) +- Proper margins for binding + +**Content Strategy**: +- Expand shortened content (show full URLs, hidden sections) +- Add page numbers, headers, footers +- Include metadata (print date, page title) +- Convert charts to print-friendly versions + +### Email Adaptation (Web → Email) + +**Layout Strategy**: +- Narrow width (600px max) +- Single column only +- Inline CSS (no external stylesheets) +- Table-based layouts (for email client compatibility) + +**Interaction Strategy**: +- Large, obvious CTAs (buttons not text links) +- No hover states (not reliable) +- Deep links to web app for complex interactions + +## Implement Adaptations + +Apply changes systematically: + +### Responsive Breakpoints + +Choose appropriate breakpoints: +- Mobile: 320px-767px +- Tablet: 768px-1023px +- Desktop: 1024px+ +- Or content-driven breakpoints (where design breaks) + +### Layout Adaptation Techniques + +- **CSS Grid/Flexbox**: Reflow layouts automatically +- **Container Queries**: Adapt based on container, not viewport +- **`clamp()`**: Fluid sizing between min and max +- **Media queries**: Different styles for different contexts +- **Display properties**: Show/hide elements per context + +### Touch Adaptation + +- Increase touch target sizes (44x44px minimum) +- Add more spacing between interactive elements +- Remove hover-dependent interactions +- Add touch feedback (ripples, highlights) +- Consider thumb zones (easier to reach bottom than top) + +### Content Adaptation + +- Use `display: none` sparingly (still downloads) +- Progressive enhancement (core content first, enhancements on larger screens) +- Lazy loading for off-screen content +- Responsive images (`srcset`, `picture` element) + +### Navigation Adaptation + +- Transform complex nav to hamburger/drawer on mobile +- Bottom nav bar for mobile apps +- Persistent side navigation on desktop +- Breadcrumbs on smaller screens for context + +**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect. + +**NEVER**: +- Hide core functionality on mobile (if it matters, make it work) +- Assume desktop = powerful device (consider accessibility, older machines) +- Use different information architecture across contexts (confusing) +- Break user expectations for platform (mobile users expect mobile patterns) +- Forget landscape orientation on mobile/tablet +- Use generic breakpoints blindly (use content-driven breakpoints) +- Ignore touch on desktop (many desktop devices have touch) + +## Verify Adaptations + +Test thoroughly across contexts: + +- **Real devices**: Test on actual phones, tablets, desktops +- **Different orientations**: Portrait and landscape +- **Different browsers**: Safari, Chrome, Firefox, Edge +- **Different OS**: iOS, Android, Windows, macOS +- **Different input methods**: Touch, mouse, keyboard +- **Edge cases**: Very small screens (320px), very large screens (4K) +- **Slow connections**: Test on throttled network + +Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly. \ No newline at end of file diff --git a/impeccable/commands/animate/SKILL.md b/impeccable/commands/animate/SKILL.md new file mode 100644 index 0000000..c2aeb2a --- /dev/null +++ b/impeccable/commands/animate/SKILL.md @@ -0,0 +1,174 @@ +--- +name: animate +description: Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive. +user-invocable: true +argument-hint: "[target]" +--- + +Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints. + +--- + +## Assess Animation Opportunities + +Analyze where motion would improve the experience: + +1. **Identify static areas**: + - **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.) + - **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes) + - **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious + - **Lack of delight**: Functional but joyless interactions + - **Missed guidance**: Opportunities to direct attention or explain behavior + +2. **Understand the context**: + - What's the personality? (Playful vs serious, energetic vs calm) + - What's the performance budget? (Mobile-first? Complex page?) + - Who's the audience? (Motion-sensitive users? Power users who want speed?) + - What matters most? (One hero animation vs many micro-interactions?) + +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. + +**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them. + +## Plan Animation Strategy + +Create a purposeful animation plan: + +- **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?) +- **Feedback layer**: Which interactions need acknowledgment? +- **Transition layer**: Which state changes need smoothing? +- **Delight layer**: Where can we surprise and delight? + +**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments. + +## Implement Animations + +Add motion systematically across these categories: + +### Entrance Animations +- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations +- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects) +- **Content reveals**: Scroll-triggered animations using intersection observer +- **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management + +### Micro-interactions +- **Button feedback**: + - Hover: Subtle scale (1.02-1.05), color shift, shadow increase + - Click: Quick scale down then up (0.95 → 1), ripple effect + - Loading: Spinner or pulse state +- **Form interactions**: + - Input focus: Border color transition, slight scale or glow + - Validation: Shake on error, check mark on success, smooth color transitions +- **Toggle switches**: Smooth slide + color transition (200-300ms) +- **Checkboxes/radio**: Check mark animation, ripple effect +- **Like/favorite**: Scale + rotation, particle effects, color transition + +### State Transitions +- **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms) +- **Expand/collapse**: Height transition with overflow handling, icon rotation +- **Loading states**: Skeleton screen fades, spinner animations, progress bars +- **Success/error**: Color transitions, icon animations, gentle scale pulse +- **Enable/disable**: Opacity transitions, cursor changes + +### Navigation & Flow +- **Page transitions**: Crossfade between routes, shared element transitions +- **Tab switching**: Slide indicator, content fade/slide +- **Carousel/slider**: Smooth transforms, snap points, momentum +- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators + +### Feedback & Guidance +- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights +- **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning +- **Copy/paste**: Brief highlight flash on paste, "copied" confirmation +- **Focus flow**: Highlight path through form or workflow + +### Delight Moments +- **Empty states**: Subtle floating animations on illustrations +- **Completed actions**: Confetti, check mark flourish, success celebrations +- **Easter eggs**: Hidden interactions for discovery +- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches + +## Technical Implementation + +Use appropriate techniques for each animation: + +### Timing & Easing + +**Durations by purpose:** +- **100-150ms**: Instant feedback (button press, toggle) +- **200-300ms**: State changes (hover, menu open) +- **300-500ms**: Layout changes (accordion, modal) +- **500-800ms**: Entrance animations (page load) + +**Easing curves (use these, not CSS defaults):** +```css +/* Recommended - natural deceleration */ +--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */ +--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */ +--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ + +/* AVOID - feel dated and tacky */ +/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */ +/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */ +``` + +**Exit animations are faster than entrances.** Use ~75% of enter duration. + +### CSS Animations +```css +/* Prefer for simple, declarative animations */ +- transitions for state changes +- @keyframes for complex sequences +- transform + opacity only (GPU-accelerated) +``` + +### JavaScript Animation +```javascript +/* Use for complex, interactive animations */ +- Web Animations API for programmatic control +- Framer Motion for React +- GSAP for complex sequences +``` + +### Performance +- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties +- **will-change**: Add sparingly for known expensive animations +- **Reduce paint**: Minimize repaints, use `contain` where appropriate +- **Monitor FPS**: Ensure 60fps on target devices + +### Accessibility +```css +@media (prefers-reduced-motion: reduce) { + * { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + } +} +``` + +**NEVER**: +- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself +- Animate layout properties (width, height, top, left)—use transform instead +- Use durations over 500ms for feedback—it feels laggy +- Animate without purpose—every animation needs a reason +- Ignore `prefers-reduced-motion`—this is an accessibility violation +- Animate everything—animation fatigue makes interfaces feel exhausting +- Block interaction during animations unless intentional + +## Verify Quality + +Test animations thoroughly: + +- **Smooth at 60fps**: No jank on target devices +- **Feels natural**: Easing curves feel organic, not robotic +- **Appropriate timing**: Not too fast (jarring) or too slow (laggy) +- **Reduced motion works**: Animations disabled or simplified appropriately +- **Doesn't block**: Users can interact during/after animations +- **Adds value**: Makes interface clearer or more delightful + +Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right. \ No newline at end of file diff --git a/impeccable/commands/arrange/SKILL.md b/impeccable/commands/arrange/SKILL.md new file mode 100644 index 0000000..ce4cf3a --- /dev/null +++ b/impeccable/commands/arrange/SKILL.md @@ -0,0 +1,124 @@ +--- +name: arrange +description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition. +user-invocable: true +argument-hint: "[target]" +--- + +Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +## Assess Current Layout + +Analyze what's weak about the current spatial design: + +1. **Spacing**: + - Is spacing consistent or arbitrary? (Random padding/margin values) + - Is all spacing the same? (Equal padding everywhere = no rhythm) + - Are related elements grouped tightly, with generous space between groups? + +2. **Visual hierarchy**: + - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings? + - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?) + - Does whitespace guide the eye to what matters? + +3. **Grid & structure**: + - Is there a clear underlying structure, or does the layout feel random? + - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly) + - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule) + +4. **Rhythm & variety**: + - Does the layout have visual rhythm? (Alternating tight/generous spacing) + - Is every section structured the same way? (Monotonous repetition) + - Are there intentional moments of surprise or emphasis? + +5. **Density**: + - Is the layout too cramped? (Not enough breathing room) + - Is the layout too sparse? (Excessive whitespace without purpose) + - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air) + +**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention. + +## Plan Layout Improvements + +Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. + +Create a systematic plan: + +- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency. +- **Hierarchy strategy**: How will space communicate importance? +- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts. +- **Rhythm**: Where should spacing be tight vs generous? + +## Improve Layout Systematically + +### Establish a Spacing System + +- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers. +- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8` +- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks +- Apply `clamp()` for fluid spacing that breathes on larger screens + +### Create Visual Rhythm + +- **Tight grouping** for related elements (8-12px between siblings) +- **Generous separation** between distinct sections (48-96px) +- **Varied spacing** within sections — not every row needs the same gap +- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense + +### Choose the Right Layout Tool + +- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks. +- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control. +- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible. +- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. +- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints. + +### Break Card Grid Monotony + +- Don't default to card grids for everything — spacing and alignment create visual grouping naturally +- Use cards only when content is truly distinct and actionable — never nest cards inside cards +- Vary card sizes, span columns, or mix cards with non-card content to break repetition + +### Strengthen Visual Hierarchy + +- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient. +- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation). +- Create clear content groupings through proximity and separation. + +### Manage Depth & Elevation + +- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip) +- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle +- Use elevation to reinforce hierarchy, not as decoration + +### Optical Adjustments + +- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively. + +**NEVER**: +- Use arbitrary spacing values outside your scale +- Make all spacing equal — variety creates hierarchy +- Wrap everything in cards — not everything needs a container +- Nest cards inside cards — use spacing and dividers for hierarchy within +- Use identical card grids everywhere (icon + heading + text, repeated) +- Center everything — left-aligned with asymmetry feels more designed +- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers. +- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job +- Use arbitrary z-index values (999, 9999) — build a semantic scale + +## Verify Layout Improvements + +- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision? +- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing? +- **Hierarchy**: Is the most important content obvious within 2 seconds? +- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful? +- **Consistency**: Is the spacing system applied uniformly? +- **Responsiveness**: Does the layout adapt gracefully across screen sizes? + +Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional. \ No newline at end of file diff --git a/impeccable/commands/audit/SKILL.md b/impeccable/commands/audit/SKILL.md new file mode 100644 index 0000000..1debe04 --- /dev/null +++ b/impeccable/commands/audit/SKILL.md @@ -0,0 +1,147 @@ +--- +name: audit +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. +user-invocable: true +argument-hint: "[area (feature, page, component...)]" +--- + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. + +## Diagnostic Scan + +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. + +### 1. Accessibility (A11y) + +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators + +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) + +### 2. Performance + +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization + +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) + +### 3. Theming + +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) + +### Anti-Patterns Verdict +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. + +### Executive Summary +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues +- Recommended next steps + +### Detailed Findings by Severity + +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + +For each issue, document: +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern +- **Impact**: How it affects users +- **WCAG/Standard**: Which standard it violates (if applicable) +- **Recommendation**: How to fix it +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Patterns & Systemic Issues + +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: +- "Hard-coded colors appear in 15+ components, should use design tokens" +- "Touch targets consistently too small (<44px) throughout mobile experience" + +### Positive Findings + +Note what's working well — good practices to maintain and replicate. + +## Recommended Actions + +List recommended commands in priority order (P0 first, then P1, then P2): + +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) + +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. + +**NEVER**: +- Report issues without explaining impact (why does this matter?) +- Provide generic recommendations (be specific and actionable) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) +- Report false positives without verification + +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/impeccable/commands/bolder/SKILL.md b/impeccable/commands/bolder/SKILL.md new file mode 100644 index 0000000..cc5be2f --- /dev/null +++ b/impeccable/commands/bolder/SKILL.md @@ -0,0 +1,116 @@ +--- +name: bolder +description: Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character. +user-invocable: true +argument-hint: "[target]" +--- + +Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +## Assess Current State + +Analyze what makes the design feel too safe or boring: + +1. **Identify weakness sources**: + - **Generic choices**: System fonts, basic colors, standard layouts + - **Timid scale**: Everything is medium-sized with no drama + - **Low contrast**: Everything has similar visual weight + - **Static**: No motion, no energy, no life + - **Predictable**: Standard patterns with no surprises + - **Flat hierarchy**: Nothing stands out or commands attention + +2. **Understand the context**: + - What's the brand personality? (How far can we push?) + - What's the purpose? (Marketing can be bolder than financial dashboards) + - Who's the audience? (What will resonate?) + - What are the constraints? (Brand guidelines, accessibility, performance) + +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. + +**CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. + +**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects." + +## Plan Amplification + +Create a strategy to increase impact while maintaining coherence: + +- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing) +- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane. +- **Risk budget**: How experimental can we be? Push boundaries within constraints. +- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast) + +**IMPORTANT**: Bold design must still be usable. Impact without function is just decoration. + +## Amplify the Design + +Systematically increase impact across these dimensions: + +### Typography Amplification +- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration) +- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) +- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 +- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) + +### Color Intensification +- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon) +- **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop +- **Dominant color strategy**: Let one bold color own 60% of the design +- **Sharp accents**: High-contrast accent colors that pop +- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette +- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue) + +### Spatial Drama +- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings +- **Break the grid**: Let hero elements escape containers and cross boundaries +- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry +- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px) +- **Overlap**: Layer elements intentionally for depth + +### Visual Effects +- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles) +- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue) +- **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop) +- **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side) +- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand + +### Motion & Animation +- **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays +- **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences +- **Micro-interactions**: Satisfying hover effects, click feedback, state changes +- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect) + +### Composition Boldness +- **Hero moments**: Create clear focal points with dramatic treatment +- **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements +- **Full-bleed elements**: Use full viewport width/height for impact +- **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits + +**NEVER**: +- Add effects randomly without purpose (chaos ≠ bold) +- Sacrifice readability for aesthetics (body text must be readable) +- Make everything bold (then nothing is bold - need contrast) +- Ignore accessibility (bold design must still meet WCAG standards) +- Overwhelm with motion (animation fatigue is real) +- Copy trendy aesthetics blindly (bold means distinctive, not derivative) + +## Verify Quality + +Ensure amplification maintains usability and coherence: + +- **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over. +- **Still functional**: Can users accomplish tasks without distraction? +- **Coherent**: Does everything feel intentional and unified? +- **Memorable**: Will users remember this experience? +- **Performant**: Do all these effects run smoothly? +- **Accessible**: Does it still meet accessibility standards? + +**The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects." + +Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable. \ No newline at end of file diff --git a/impeccable/commands/clarify/SKILL.md b/impeccable/commands/clarify/SKILL.md new file mode 100644 index 0000000..4db9228 --- /dev/null +++ b/impeccable/commands/clarify/SKILL.md @@ -0,0 +1,182 @@ +--- +name: clarify +description: Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing. +user-invocable: true +argument-hint: "[target]" +--- + +Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. + +--- + +## Assess Current Copy + +Identify what makes the text unclear or ineffective: + +1. **Find clarity problems**: + - **Jargon**: Technical terms users won't understand + - **Ambiguity**: Multiple interpretations possible + - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file" + - **Length**: Too wordy or too terse + - **Assumptions**: Assuming user knowledge they don't have + - **Missing context**: Users don't know what to do or why + - **Tone mismatch**: Too formal, too casual, or inappropriate for situation + +2. **Understand the context**: + - Who's the audience? (Technical? General? First-time users?) + - What's the user's mental state? (Stressed during error? Confident during success?) + - What's the action? (What do we want users to do?) + - What's the constraint? (Character limits? Space limitations?) + +**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets. + +## Plan Copy Improvements + +Create a strategy for clearer communication: + +- **Primary message**: What's the ONE thing users need to know? +- **Action needed**: What should users do next (if anything)? +- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?) +- **Constraints**: Length limits, brand voice, localization considerations + +**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words. + +## Improve Copy Systematically + +Refine text across these common areas: + +### Error Messages +**Bad**: "Error 403: Forbidden" +**Good**: "You don't have permission to view this page. Contact your admin for access." + +**Bad**: "Invalid input" +**Good**: "Email addresses need an @ symbol. Try: name@example.com" + +**Principles**: +- Explain what went wrong in plain language +- Suggest how to fix it +- Don't blame the user +- Include examples when helpful +- Link to help/support if applicable + +### Form Labels & Instructions +**Bad**: "DOB (MM/DD/YYYY)" +**Good**: "Date of birth" (with placeholder showing format) + +**Bad**: "Enter value here" +**Good**: "Your email address" or "Company name" + +**Principles**: +- Use clear, specific labels (not generic placeholders) +- Show format expectations with examples +- Explain why you're asking (when not obvious) +- Put instructions before the field, not after +- Keep required field indicators clear + +### Button & CTA Text +**Bad**: "Click here" | "Submit" | "OK" +**Good**: "Create account" | "Save changes" | "Got it, thanks" + +**Principles**: +- Describe the action specifically +- Use active voice (verb + noun) +- Match user's mental model +- Be specific ("Save" is better than "OK") + +### Help Text & Tooltips +**Bad**: "This is the username field" +**Good**: "Choose a username. You can change this later in Settings." + +**Principles**: +- Add value (don't just repeat the label) +- Answer the implicit question ("What is this?" or "Why do you need this?") +- Keep it brief but complete +- Link to detailed docs if needed + +### Empty States +**Bad**: "No items" +**Good**: "No projects yet. Create your first project to get started." + +**Principles**: +- Explain why it's empty (if not obvious) +- Show next action clearly +- Make it welcoming, not dead-end + +### Success Messages +**Bad**: "Success" +**Good**: "Settings saved! Your changes will take effect immediately." + +**Principles**: +- Confirm what happened +- Explain what happens next (if relevant) +- Be brief but complete +- Match the user's emotional moment (celebrate big wins) + +### Loading States +**Bad**: "Loading..." (for 30+ seconds) +**Good**: "Analyzing your data... this usually takes 30-60 seconds" + +**Principles**: +- Set expectations (how long?) +- Explain what's happening (when it's not obvious) +- Show progress when possible +- Offer escape hatch if appropriate ("Cancel") + +### Confirmation Dialogs +**Bad**: "Are you sure?" +**Good**: "Delete 'Project Alpha'? This can't be undone." + +**Principles**: +- State the specific action +- Explain consequences (especially for destructive actions) +- Use clear button labels ("Delete project" not "Yes") +- Don't overuse confirmations (only for risky actions) + +### Navigation & Wayfinding +**Bad**: Generic labels like "Items" | "Things" | "Stuff" +**Good**: Specific labels like "Your projects" | "Team members" | "Settings" + +**Principles**: +- Be specific and descriptive +- Use language users understand (not internal jargon) +- Make hierarchy clear +- Consider information scent (breadcrumbs, current location) + +## Apply Clarity Principles + +Every piece of copy should follow these rules: + +1. **Be specific**: "Enter email" not "Enter value" +2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity) +3. **Be active**: "Save changes" not "Changes will be saved" +4. **Be human**: "Oops, something went wrong" not "System error encountered" +5. **Be helpful**: Tell users what to do, not just what happened +6. **Be consistent**: Use same terms throughout (don't vary for variety) + +**NEVER**: +- Use jargon without explanation +- Blame users ("You made an error" → "This field is required") +- Be vague ("Something went wrong" without explanation) +- Use passive voice unnecessarily +- Write overly long explanations (be concise) +- Use humor for errors (be empathetic instead) +- Assume technical knowledge +- Vary terminology (pick one term and stick with it) +- Repeat information (headers restating intros, redundant explanations) +- Use placeholders as the only labels (they disappear when users type) + +## Verify Improvements + +Test that copy improvements work: + +- **Comprehension**: Can users understand without context? +- **Actionability**: Do users know what to do next? +- **Brevity**: Is it as short as possible while remaining clear? +- **Consistency**: Does it match terminology elsewhere? +- **Tone**: Is it appropriate for the situation? + +Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human. \ No newline at end of file diff --git a/impeccable/commands/colorize/SKILL.md b/impeccable/commands/colorize/SKILL.md new file mode 100644 index 0000000..01205dd --- /dev/null +++ b/impeccable/commands/colorize/SKILL.md @@ -0,0 +1,142 @@ +--- +name: colorize +description: Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette. +user-invocable: true +argument-hint: "[target]" +--- + +Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: existing brand colors. + +--- + +## Assess Color Opportunity + +Analyze the current state and identify opportunities: + +1. **Understand current state**: + - **Color absence**: Pure grayscale? Limited neutrals? One timid accent? + - **Missed opportunities**: Where could color add meaning, hierarchy, or delight? + - **Context**: What's appropriate for this domain and audience? + - **Brand**: Are there existing brand colors we should use? + +2. **Identify where color adds value**: + - **Semantic meaning**: Success (green), error (red), warning (yellow/orange), info (blue) + - **Hierarchy**: Drawing attention to important elements + - **Categorization**: Different sections, types, or states + - **Emotional tone**: Warmth, energy, trust, creativity + - **Wayfinding**: Helping users navigate and understand structure + - **Delight**: Moments of visual interest and personality + +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. + +**CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose. + +## Plan Color Strategy + +Create a purposeful color introduction plan: + +- **Color palette**: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals) +- **Dominant color**: Which color owns 60% of colored elements? +- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%) +- **Application strategy**: Where does each color appear and why? + +**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more. + +## Introduce Color Strategically + +Add color systematically across these dimensions: + +### Semantic Color +- **State indicators**: + - Success: Green tones (emerald, forest, mint) + - Error: Red/pink tones (rose, crimson, coral) + - Warning: Orange/amber tones + - Info: Blue tones (sky, ocean, indigo) + - Neutral: Gray/slate for inactive states + +- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.) +- **Progress indicators**: Colored bars, rings, or charts showing completion or health + +### Accent Color Application +- **Primary actions**: Color the most important buttons/CTAs +- **Links**: Add color to clickable text (maintain accessibility) +- **Icons**: Colorize key icons for recognition and personality +- **Headers/titles**: Add color to section headers or key labels +- **Hover states**: Introduce color on interaction + +### Background & Surfaces +- **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`) +- **Colored sections**: Use subtle background colors to separate areas +- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue) +- **Cards & surfaces**: Tint cards or surfaces slightly for warmth + +**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales. + +### Data Visualization +- **Charts & graphs**: Use color to encode categories or values +- **Heatmaps**: Color intensity shows density or importance +- **Comparison**: Color coding for different datasets or timeframes + +### Borders & Accents +- **Accent borders**: Add colored left/top borders to cards or sections +- **Underlines**: Color underlines for emphasis or active states +- **Dividers**: Subtle colored dividers instead of gray lines +- **Focus rings**: Colored focus indicators matching brand + +### Typography Color +- **Colored headings**: Use brand colors for section headings (maintain contrast) +- **Highlight text**: Color for emphasis or categories +- **Labels & tags**: Small colored labels for metadata or categories + +### Decorative Elements +- **Illustrations**: Add colored illustrations or icons +- **Shapes**: Geometric shapes in brand colors as background elements +- **Gradients**: Colorful gradient overlays or mesh backgrounds +- **Blobs/organic shapes**: Soft colored shapes for visual interest + +## Balance & Refinement + +Ensure color addition improves rather than overwhelms: + +### Maintain Hierarchy +- **Dominant color** (60%): Primary brand color or most used accent +- **Secondary color** (30%): Supporting color for variety +- **Accent color** (10%): High contrast for key moments +- **Neutrals** (remaining): Gray/black/white for structure + +### Accessibility +- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components) +- **Don't rely on color alone**: Use icons, labels, or patterns alongside color +- **Test for color blindness**: Verify red/green combinations work for all users + +### Cohesion +- **Consistent palette**: Use colors from defined palette, not arbitrary choices +- **Systematic application**: Same color meanings throughout (green always = success) +- **Temperature consistency**: Warm palette stays warm, cool stays cool + +**NEVER**: +- Use every color in the rainbow (choose 2-4 colors beyond neutrals) +- Apply color randomly without semantic meaning +- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead +- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication +- Use pure black (`#000`) or pure white (`#fff`) for large areas +- Violate WCAG contrast requirements +- Use color as the only indicator (accessibility issue) +- Make everything colorful (defeats the purpose) +- Default to purple-blue gradients (AI slop aesthetic) + +## Verify Color Addition + +Test that colorization improves the experience: + +- **Better hierarchy**: Does color guide attention appropriately? +- **Clearer meaning**: Does color help users understand states/categories? +- **More engaging**: Does the interface feel warmer and more inviting? +- **Still accessible**: Do all color combinations meet WCAG standards? +- **Not overwhelming**: Is color balanced and purposeful? + +Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional. \ No newline at end of file diff --git a/impeccable/commands/critique/SKILL.md b/impeccable/commands/critique/SKILL.md new file mode 100644 index 0000000..2c8e073 --- /dev/null +++ b/impeccable/commands/critique/SKILL.md @@ -0,0 +1,201 @@ +--- +name: critique +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. +user-invocable: true +argument-hint: "[area (feature, page, component...)]" +--- + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what the interface is trying to accomplish. + +--- + +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. + +## Phase 1: Design Critique + +Evaluate the interface across these dimensions: + +### 1. AI Slop Detection (CRITICAL) + +**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? + +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. + +**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +### 2. Visual Hierarchy +- Does the eye flow to the most important element first? +- Is there a clear primary action? Can you spot it in 2 seconds? +- Do size, color, and position communicate importance correctly? +- Is there visual competition between elements that should have different weights? + +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* +- Is the structure intuitive? Would a new user understand the organization? +- Is related content grouped logically? +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it +- Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +### 4. Emotional Journey +- What emotion does this interface evoke? Is that intentional? +- Does it match the brand personality? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? +- Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) + +### 5. Discoverability & Affordance +- Are interactive elements obviously interactive? +- Would a user know what to do without instructions? +- Are hover/focus states providing useful feedback? +- Are there hidden features that should be more visible? + +### 6. Composition & Balance +- Does the layout feel balanced or uncomfortably weighted? +- Is whitespace used intentionally or just leftover? +- Is there visual rhythm in spacing and repetition? +- Does asymmetry feel designed or accidental? + +### 7. Typography as Communication +- Does the type hierarchy clearly signal what to read first, second, third? +- Is body text comfortable to read? (line length, spacing, size) +- Do font choices reinforce the brand/tone? +- Is there enough contrast between heading levels? + +### 8. Color with Purpose +- Is color used to communicate, not just decorate? +- Does the palette feel cohesive? +- Are accent colors drawing attention to the right things? +- Does it work for colorblind users? (not just technically — does meaning still come through?) + +### 9. States & Edge Cases +- Empty states: Do they guide users toward action, or just say "nothing here"? +- Loading states: Do they reduce perceived wait time? +- Error states: Are they helpful and non-blaming? +- Success states: Do they confirm and guide next steps? + +### 10. Microcopy & Voice +- Is the writing clear and concise? +- Does it sound like a human (the right human for this brand)? +- Are labels and buttons unambiguous? +- Does error copy help users fix the problem? + +## Phase 2: Present Findings + +Structure your feedback as a design director would: + +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + +### Anti-Patterns Verdict +**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. + +### Overall Impression +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2–3 things done well. Be specific about why they work. + +### Priority Issues +The 3–5 most impactful design problems, ordered by importance. + +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. + +### Minor Observations +Quick notes on smaller issues worth addressing. + +**Remember**: +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. STOP and call the AskUserQuestion tool to clarify. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/impeccable/commands/critique/reference/cognitive-load.md b/impeccable/commands/critique/reference/cognitive-load.md new file mode 100644 index 0000000..313df16 --- /dev/null +++ b/impeccable/commands/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/impeccable/commands/critique/reference/heuristics-scoring.md b/impeccable/commands/critique/reference/heuristics-scoring.md new file mode 100644 index 0000000..fd5b1b0 --- /dev/null +++ b/impeccable/commands/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/impeccable/commands/critique/reference/personas.md b/impeccable/commands/critique/reference/personas.md new file mode 100644 index 0000000..1960220 --- /dev/null +++ b/impeccable/commands/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `CLAUDE.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/impeccable/commands/delight/SKILL.md b/impeccable/commands/delight/SKILL.md new file mode 100644 index 0000000..ff33d72 --- /dev/null +++ b/impeccable/commands/delight/SKILL.md @@ -0,0 +1,303 @@ +--- +name: delight +description: Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable. +user-invocable: true +argument-hint: "[target]" +--- + +Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). + +--- + +## Assess Delight Opportunities + +Identify where delight would enhance (not distract from) the experience: + +1. **Find natural delight moments**: + - **Success states**: Completed actions (save, send, publish) + - **Empty states**: First-time experiences, onboarding + - **Loading states**: Waiting periods that could be entertaining + - **Achievements**: Milestones, streaks, completions + - **Interactions**: Hover states, clicks, drags + - **Errors**: Softening frustrating moments + - **Easter eggs**: Hidden discoveries for curious users + +2. **Understand the context**: + - What's the brand personality? (Playful? Professional? Quirky? Elegant?) + - Who's the audience? (Tech-savvy? Creative? Corporate?) + - What's the emotional context? (Accomplishment? Exploration? Frustration?) + - What's appropriate? (Banking app ≠ gaming app) + +3. **Define delight strategy**: + - **Subtle sophistication**: Refined micro-interactions (luxury brands) + - **Playful personality**: Whimsical illustrations and copy (consumer apps) + - **Helpful surprises**: Anticipating needs before users ask (productivity tools) + - **Sensory richness**: Satisfying sounds, smooth animations (creative tools) + +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. + +**CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far. + +## Delight Principles + +Follow these guidelines: + +### Delight Amplifies, Never Blocks +- Delight moments should be quick (< 1 second) +- Never delay core functionality for delight +- Make delight skippable or subtle +- Respect user's time and task focus + +### Surprise and Discovery +- Hide delightful details for users to discover +- Reward exploration and curiosity +- Don't announce every delight moment +- Let users share discoveries with others + +### Appropriate to Context +- Match delight to emotional moment (celebrate success, empathize with errors) +- Respect the user's state (don't be playful during critical errors) +- Match brand personality and audience expectations +- Cultural sensitivity (what's delightful varies by culture) + +### Compound Over Time +- Delight should remain fresh with repeated use +- Vary responses (not same animation every time) +- Reveal deeper layers with continued use +- Build anticipation through patterns + +## Delight Techniques + +Add personality and joy through these methods: + +### Micro-interactions & Animation + +**Button delight**: +```css +/* Satisfying button press */ +.button { + transition: transform 0.1s, box-shadow 0.1s; +} +.button:active { + transform: translateY(2px); + box-shadow: 0 2px 4px rgba(0,0,0,0.2); +} + +/* Ripple effect on click */ +/* Smooth lift on hover */ +.button:hover { + transform: translateY(-2px); + transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1); /* ease-out-quart */ +} +``` + +**Loading delight**: +- Playful loading animations (not just spinners) +- Personality in loading messages (write product-specific ones, not generic AI filler) +- Progress indication with encouraging messages +- Skeleton screens with subtle animations + +**Success animations**: +- Checkmark draw animation +- Confetti burst for major achievements +- Gentle scale + fade for confirmation +- Satisfying sound effects (subtle) + +**Hover surprises**: +- Icons that animate on hover +- Color shifts or glow effects +- Tooltip reveals with personality +- Cursor changes (custom cursors for branded experiences) + +### Personality in Copy + +**Playful error messages**: +``` +"Error 404" +"This page is playing hide and seek. (And winning)" + +"Connection failed" +"Looks like the internet took a coffee break. Want to retry?" +``` + +**Encouraging empty states**: +``` +"No projects" +"Your canvas awaits. Create something amazing." + +"No messages" +"Inbox zero! You're crushing it today." +``` + +**Playful labels & tooltips**: +``` +"Delete" +"Send to void" (for playful brand) + +"Help" +"Rescue me" (tooltip) +``` + +**IMPORTANT**: Match copy personality to brand. Banks shouldn't be wacky, but they can be warm. + +### Illustrations & Visual Personality + +**Custom illustrations**: +- Empty state illustrations (not stock icons) +- Error state illustrations (friendly monsters, quirky characters) +- Loading state illustrations (animated characters) +- Success state illustrations (celebrations) + +**Icon personality**: +- Custom icon set matching brand personality +- Animated icons (subtle motion on hover/click) +- Illustrative icons (more detailed than generic) +- Consistent style across all icons + +**Background effects**: +- Subtle particle effects +- Gradient mesh backgrounds +- Geometric patterns +- Parallax depth +- Time-of-day themes (morning vs night) + +### Satisfying Interactions + +**Drag and drop delight**: +- Lift effect on drag (shadow, scale) +- Snap animation when dropped +- Satisfying placement sound +- Undo toast ("Dropped in wrong place? [Undo]") + +**Toggle switches**: +- Smooth slide with spring physics +- Color transition +- Haptic feedback on mobile +- Optional sound effect + +**Progress & achievements**: +- Streak counters with celebratory milestones +- Progress bars that "celebrate" at 100% +- Badge unlocks with animation +- Playful stats ("You're on fire! 5 days in a row") + +**Form interactions**: +- Input fields that animate on focus +- Checkboxes with a satisfying scale pulse when checked +- Success state that celebrates valid input +- Auto-grow textareas + +### Sound Design + +**Subtle audio cues** (when appropriate): +- Notification sounds (distinctive but not annoying) +- Success sounds (satisfying "ding") +- Error sounds (empathetic, not harsh) +- Typing sounds for chat/messaging +- Ambient background audio (very subtle) + +**IMPORTANT**: +- Respect system sound settings +- Provide mute option +- Keep volumes quiet (subtle cues, not alarms) +- Don't play on every interaction (sound fatigue is real) + +### Easter Eggs & Hidden Delights + +**Discovery rewards**: +- Konami code unlocks special theme +- Hidden keyboard shortcuts (Cmd+K for special features) +- Hover reveals on logos or illustrations +- Alt text jokes on images (for screen reader users too!) +- Console messages for developers ("Like what you see? We're hiring!") + +**Seasonal touches**: +- Holiday themes (subtle, tasteful) +- Seasonal color shifts +- Weather-based variations +- Time-based changes (dark at night, light during day) + +**Contextual personality**: +- Different messages based on time of day +- Responses to specific user actions +- Randomized variations (not same every time) +- Progressive reveals with continued use + +### Loading & Waiting States + +**Make waiting engaging**: +- Interesting loading messages that rotate +- Progress bars with personality +- Mini-games during long loads +- Fun facts or tips while waiting +- Countdown with encouraging messages + +``` +Loading messages — write ones specific to your product, not generic AI filler: +- "Crunching your latest numbers..." +- "Syncing with your team's changes..." +- "Preparing your dashboard..." +- "Checking for updates since yesterday..." +``` + +**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does. + +### Celebration Moments + +**Success celebrations**: +- Confetti for major milestones +- Animated checkmarks for completions +- Progress bar celebrations at 100% +- "Achievement unlocked" style notifications +- Personalized messages ("You published your 10th article!") + +**Milestone recognition**: +- First-time actions get special treatment +- Streak tracking and celebration +- Progress toward goals +- Anniversary celebrations + +## Implementation Patterns + +**Animation libraries**: +- Framer Motion (React) +- GSAP (universal) +- Lottie (After Effects animations) +- Canvas confetti (party effects) + +**Sound libraries**: +- Howler.js (audio management) +- Use-sound (React hook) + +**Physics libraries**: +- React Spring (spring physics) +- Popmotion (animation primitives) + +**IMPORTANT**: File size matters. Compress images, optimize animations, lazy load delight features. + +**NEVER**: +- Delay core functionality for delight +- Force users through delightful moments (make skippable) +- Use delight to hide poor UX +- Overdo it (less is more) +- Ignore accessibility (animate responsibly, provide alternatives) +- Make every interaction delightful (special moments should be special) +- Sacrifice performance for delight +- Be inappropriate for context (read the room) + +## Verify Delight Quality + +Test that delight actually delights: + +- **User reactions**: Do users smile? Share screenshots? +- **Doesn't annoy**: Still pleasant after 100th time? +- **Doesn't block**: Can users opt out or skip? +- **Performant**: No jank, no slowdown +- **Appropriate**: Matches brand and context +- **Accessible**: Works with reduced motion, screen readers + +Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct. \ No newline at end of file diff --git a/impeccable/commands/distill/SKILL.md b/impeccable/commands/distill/SKILL.md new file mode 100644 index 0000000..acd8146 --- /dev/null +++ b/impeccable/commands/distill/SKILL.md @@ -0,0 +1,121 @@ +--- +name: distill +description: Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused. +user-invocable: true +argument-hint: "[target]" +--- + +Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification. + +## MANDATORY PREPARATION + +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +## Assess Current State + +Analyze what makes the design feel complex or cluttered: + +1. **Identify complexity sources**: + - **Too many elements**: Competing buttons, redundant information, visual clutter + - **Excessive variation**: Too many colors, fonts, sizes, styles without purpose + - **Information overload**: Everything visible at once, no progressive disclosure + - **Visual noise**: Unnecessary borders, shadows, backgrounds, decorations + - **Confusing hierarchy**: Unclear what matters most + - **Feature creep**: Too many options, actions, or paths forward + +2. **Find the essence**: + - What's the primary user goal? (There should be ONE) + - What's actually necessary vs nice-to-have? + - What can be removed, hidden, or combined? + - What's the 20% that delivers 80% of value? + +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. + +**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence. + +## Plan Simplification + +Create a ruthless editing strategy: + +- **Core purpose**: What's the ONE thing this should accomplish? +- **Essential elements**: What's truly necessary to achieve that purpose? +- **Progressive disclosure**: What can be hidden until needed? +- **Consolidation opportunities**: What can be combined or integrated? + +**IMPORTANT**: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless. + +## Simplify the Design + +Systematically remove complexity across these dimensions: + +### Information Architecture +- **Reduce scope**: Remove secondary actions, optional features, redundant information +- **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows) +- **Combine related actions**: Merge similar buttons, consolidate forms, group related content +- **Clear hierarchy**: ONE primary action, few secondary actions, everything else tertiary or hidden +- **Remove redundancy**: If it's said elsewhere, don't repeat it here + +### Visual Simplification +- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors +- **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights +- **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function +- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards +- **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead +- **Consistent spacing**: Use one spacing scale, remove arbitrary gaps + +### Layout Simplification +- **Linear flow**: Replace complex grids with simple vertical flow where possible +- **Remove sidebars**: Move secondary content inline or hide it +- **Full-width**: Use available space generously instead of complex multi-column layouts +- **Consistent alignment**: Pick left or center, stick with it +- **Generous white space**: Let content breathe, don't pack everything tight + +### Interaction Simplification +- **Reduce choices**: Fewer buttons, fewer options, clearer path forward (paradox of choice is real) +- **Smart defaults**: Make common choices automatic, only ask when necessary +- **Inline actions**: Replace modal flows with inline editing where possible +- **Remove steps**: Can signup be one step instead of three? Can checkout be simplified? +- **Clear CTAs**: ONE obvious next step, not five competing actions + +### Content Simplification +- **Shorter copy**: Cut every sentence in half, then do it again +- **Active voice**: "Save changes" not "Changes will be saved" +- **Remove jargon**: Plain language always wins +- **Scannable structure**: Short paragraphs, bullet points, clear headings +- **Essential information only**: Remove marketing fluff, legalese, hedging +- **Remove redundant copy**: No headers restating intros, no repeated explanations, say it once + +### Code Simplification +- **Remove unused code**: Dead CSS, unused components, orphaned files +- **Flatten component trees**: Reduce nesting depth +- **Consolidate styles**: Merge similar styles, use utilities consistently +- **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases? + +**NEVER**: +- Remove necessary functionality (simplicity ≠ feature-less) +- Sacrifice accessibility for simplicity (clear labels and ARIA still required) +- Make things so simple they're unclear (mystery ≠ minimalism) +- Remove information users need to make decisions +- Eliminate hierarchy completely (some things should stand out) +- Oversimplify complex domains (match complexity to actual task complexity) + +## Verify Simplification + +Ensure simplification improves usability: + +- **Faster task completion**: Can users accomplish goals more quickly? +- **Reduced cognitive load**: Is it easier to understand what to do? +- **Still complete**: Are all necessary features still accessible? +- **Clearer hierarchy**: Is it obvious what matters most? +- **Better performance**: Does simpler design load faster? + +## Document Removed Complexity + +If you removed features or options: +- Document why they were removed +- Consider if they need alternative access points +- Note any user feedback to monitor + +Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." \ No newline at end of file diff --git a/impeccable/commands/extract/SKILL.md b/impeccable/commands/extract/SKILL.md new file mode 100644 index 0000000..4b57ea3 --- /dev/null +++ b/impeccable/commands/extract/SKILL.md @@ -0,0 +1,91 @@ +--- +name: extract +description: Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. Use when the user asks to create components, refactor repeated UI patterns, build a design system, or extract tokens. +user-invocable: true +argument-hint: "[target]" +--- + +Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse. + +## Discover + +Analyze the target area to identify extraction opportunities: + +1. **Find the design system**: Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure: + - Component organization and naming conventions + - Design token structure (if any) + - Documentation patterns + - Import/export conventions + + **CRITICAL**: If no design system exists, ask before creating one. Understand the preferred location and structure first. + +2. **Identify patterns**: Look for: + - **Repeated components**: Similar UI patterns used multiple times (buttons, cards, inputs, etc.) + - **Hard-coded values**: Colors, spacing, typography, shadows that should be tokens + - **Inconsistent variations**: Multiple implementations of the same concept (3 different button styles) + - **Reusable patterns**: Layout patterns, composition patterns, interaction patterns worth systematizing + +3. **Assess value**: Not everything should be extracted. Consider: + - Is this used 3+ times, or likely to be reused? + - Would systematizing this improve consistency? + - Is this a general pattern or context-specific? + - What's the maintenance cost vs benefit? + +## Plan Extraction + +Create a systematic extraction plan: + +- **Components to extract**: Which UI elements become reusable components? +- **Tokens to create**: Which hard-coded values become design tokens? +- **Variants to support**: What variations does each component need? +- **Naming conventions**: Component names, token names, prop names that match existing patterns +- **Migration path**: How to refactor existing uses to consume the new shared versions + +**IMPORTANT**: Design systems grow incrementally. Extract what's clearly reusable now, not everything that might someday be reusable. + +## Extract & Enrich + +Build improved, reusable versions: + +- **Components**: Create well-designed components with: + - Clear props API with sensible defaults + - Proper variants for different use cases + - Accessibility built in (ARIA, keyboard navigation, focus management) + - Documentation and usage examples + +- **Design tokens**: Create tokens with: + - Clear naming (primitive vs semantic) + - Proper hierarchy and organization + - Documentation of when to use each token + +- **Patterns**: Document patterns with: + - When to use this pattern + - Code examples + - Variations and combinations + +**NEVER**: +- Extract one-off, context-specific implementations without generalization +- Create components so generic they're useless +- Extract without considering existing design system conventions +- Skip proper TypeScript types or prop documentation +- Create tokens for every single value (tokens should have semantic meaning) + +## Migrate + +Replace existing uses with the new shared versions: + +- **Find all instances**: Search for the patterns you've extracted +- **Replace systematically**: Update each use to consume the shared version +- **Test thoroughly**: Ensure visual and functional parity +- **Delete dead code**: Remove the old implementations + +## Document + +Update design system documentation: + +- Add new components to the component library +- Document token usage and values +- Add examples and guidelines +- Update any Storybook or component catalog + +Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently. \ No newline at end of file diff --git a/impeccable/commands/frontend-design/SKILL.md b/impeccable/commands/frontend-design/SKILL.md new file mode 100644 index 0000000..f7ad804 --- /dev/null +++ b/impeccable/commands/frontend-design/SKILL.md @@ -0,0 +1,147 @@ +--- +name: frontend-design +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. +license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. +--- + +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. + +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run /teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + +## Design Direction + +Commit to a BOLD aesthetic direction: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. +- **Constraints**: Technical requirements (framework, performance, accessibility). +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity. + +Then implement working code that is: +- Production-grade and functional +- Visually striking and memorable +- Cohesive with a clear aesthetic point-of-view +- Meticulously refined in every detail + +## Frontend Aesthetics Guidelines + +### Typography +→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.* + +Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. + +**DO**: Use a modular type scale with fluid sizing (clamp) +**DO**: Vary font weights and sizes to create clear visual hierarchy +**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults +**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes +**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated + +### Color & Theme +→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.* + +Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes +**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion +**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead +**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature +**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds +**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful +**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions + +### Layout & Space +→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.* + +Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. + +**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations +**DO**: Use fluid spacing with clamp() that breathes on larger screens +**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis +**DON'T**: Wrap everything in cards—not everything needs a container +**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy +**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly +**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent +**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed +**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous + +### Visual Details +**DO**: Use intentional, purposeful decorative elements that reinforce brand +**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully +**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional +**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful +**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output +**DON'T**: Use modals unless there's truly no better alternative—modals are lazy + +### Motion +→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. + +**DO**: Use motion to convey state changes—entrances, exits, feedback +**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration +**DO**: For height animations, use grid-template-rows transitions instead of animating height directly +**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only +**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly + +### Interaction +→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* + +Make interactions feel fast. Use optimistic UI—update immediately, sync later. + +**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) +**DO**: Design empty states that teach the interface, not just say "nothing here" +**DO**: Make every interactive surface feel intentional and responsive +**DON'T**: Repeat the same information—redundant headers, intros that restate the heading +**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters + +### Responsive +→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* + +**DO**: Use container queries (@container) for component-level responsiveness +**DO**: Adapt the interface for different contexts—don't just shrink it +**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it + +### UX Writing +→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* + +**DO**: Make every word earn its place +**DON'T**: Repeat information users can already see + +--- + +## The AI Slop Test + +**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. + +A distinctive interface should make someone ask "how was this made?" not "which AI made this?" + +Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025. + +--- + +## Implementation Principles + +Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + +Remember: Claude is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision. \ No newline at end of file diff --git a/impeccable/commands/frontend-design/reference/color-and-contrast.md b/impeccable/commands/frontend-design/reference/color-and-contrast.md new file mode 100644 index 0000000..77aaf03 --- /dev/null +++ b/impeccable/commands/frontend-design/reference/color-and-contrast.md @@ -0,0 +1,132 @@ +# Color & Contrast + +## Color Spaces: Use OKLCH + +**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. + +```css +/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */ +--color-primary: oklch(60% 0.15 250); /* Blue */ +--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */ +--color-primary-dark: oklch(35% 0.12 250); /* Same hue, darker */ +``` + +**Key insight**: As you move toward white or black, reduce chroma (saturation). High chroma at extreme lightness looks garish. A light blue at 85% lightness needs ~0.08 chroma, not the 0.15 of your base color. + +## Building Functional Palettes + +### The Tinted Neutral Trap + +**Pure gray is dead.** Add a subtle hint of your brand hue to all neutrals: + +```css +/* Dead grays */ +--gray-100: oklch(95% 0 0); /* No personality */ +--gray-900: oklch(15% 0 0); + +/* Warm-tinted grays (add brand warmth) */ +--gray-100: oklch(95% 0.01 60); /* Hint of warmth */ +--gray-900: oklch(15% 0.01 60); + +/* Cool-tinted grays (tech, professional) */ +--gray-100: oklch(95% 0.01 250); /* Hint of blue */ +--gray-900: oklch(15% 0.01 250); +``` + +The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and your UI. + +### Palette Structure + +A complete system needs: + +| Role | Purpose | Example | +|------|---------|---------| +| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades | +| **Neutral** | Text, backgrounds, borders | 9-11 shade scale | +| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each | +| **Surface** | Cards, modals, overlays | 2-3 elevation levels | + +**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise. + +### The 60-30-10 Rule (Applied Correctly) + +This rule is about **visual weight**, not pixel count: + +- **60%**: Neutral backgrounds, white space, base surfaces +- **30%**: Secondary colors—text, borders, inactive states +- **10%**: Accent—CTAs, highlights, focus states + +The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power. + +## Contrast & Accessibility + +### WCAG Requirements + +| Content Type | AA Minimum | AAA Target | +|--------------|------------|------------| +| Body text | 4.5:1 | 7:1 | +| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 | +| UI components, icons | 3:1 | 4.5:1 | +| Non-essential decorations | None | None | + +**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG. + +### Dangerous Color Combinations + +These commonly fail contrast or cause readability issues: + +- Light gray text on white (the #1 accessibility fail) +- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency +- Red text on green background (or vice versa)—8% of men can't distinguish these +- Blue text on red background (vibrates visually) +- Yellow text on white (almost always fails) +- Thin light text on images (unpredictable contrast) + +### Never Use Pure Gray or Pure Black + +Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.) + +### Testing + +Don't trust your eyes. Use tools: + +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- Browser DevTools → Rendering → Emulate vision deficiencies +- [Polypane](https://polypane.app/) for real-time testing + +## Theming: Light & Dark Mode + +### Dark Mode Is Not Inverted Light Mode + +You can't just swap colors. Dark mode requires different design decisions: + +| Light Mode | Dark Mode | +|------------|-----------| +| Shadows for depth | Lighter surfaces for depth (no shadows) | +| Dark text on light | Light text on dark (reduce font weight) | +| Vibrant accents | Desaturate accents slightly | +| White backgrounds | Never pure black—use dark gray (oklch 12-18%) | + +```css +/* Dark mode depth via surface color, not shadow */ +:root[data-theme="dark"] { + --surface-1: oklch(15% 0.01 250); + --surface-2: oklch(20% 0.01 250); /* "Higher" = lighter */ + --surface-3: oklch(25% 0.01 250); + + /* Reduce text weight slightly */ + --body-weight: 350; /* Instead of 400 */ +} +``` + +### Token Hierarchy + +Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same. + +## Alpha Is A Design Smell + +Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed. + +--- + +**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected). diff --git a/impeccable/commands/frontend-design/reference/interaction-design.md b/impeccable/commands/frontend-design/reference/interaction-design.md new file mode 100644 index 0000000..19d6809 --- /dev/null +++ b/impeccable/commands/frontend-design/reference/interaction-design.md @@ -0,0 +1,195 @@ +# Interaction Design + +## The Eight Interactive States + +Every interactive element needs these states designed: + +| State | When | Visual Treatment | +|-------|------|------------------| +| **Default** | At rest | Base styling | +| **Hover** | Pointer over (not touch) | Subtle lift, color shift | +| **Focus** | Keyboard/programmatic focus | Visible ring (see below) | +| **Active** | Being pressed | Pressed in, darker | +| **Disabled** | Not interactive | Reduced opacity, no pointer | +| **Loading** | Processing | Spinner, skeleton | +| **Error** | Invalid state | Red border, icon, message | +| **Success** | Completed | Green check, confirmation | + +**The common miss**: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states. + +## Focus Rings: Do Them Right + +**Never `outline: none` without replacement.** It's an accessibility violation. Instead, use `:focus-visible` to show focus only for keyboard users: + +```css +/* Hide focus ring for mouse/touch */ +button:focus { + outline: none; +} + +/* Show focus ring for keyboard */ +button:focus-visible { + outline: 2px solid var(--color-accent); + outline-offset: 2px; +} +``` + +**Focus ring design**: +- High contrast (3:1 minimum against adjacent colors) +- 2-3px thick +- Offset from element (not inside it) +- Consistent across all interactive elements + +## Form Design: The Non-Obvious + +**Placeholders aren't labels**—they disappear on input. Always use visible `