wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/referral-program/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: referral-program
+description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch-strategy."
+metadata:
+  version: 1.1.0
+---
+
+# Referral & Affiliate Programs
+
+You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.
+
+## Before Starting
+
+**Check for product marketing context first:**
+If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Program Type
+- Customer referral program, affiliate program, or both?
+- B2B or B2C?
+- What's the average customer LTV?
+- What's your current CAC from other channels?
+
+### 2. Current State
+- Existing referral/affiliate program?
+- Current referral rate (% who refer)?
+- What incentives have you tried?
+
+### 3. Product Fit
+- Is your product shareable?
+- Does it have network effects?
+- Do customers naturally talk about it?
+
+### 4. Resources
+- Tools/platforms you use or consider?
+- Budget for referral incentives?
+
+---
+
+## Referral vs. Affiliate
+
+### Customer Referral Programs
+
+**Best for:**
+- Existing customers recommending to their network
+- Products with natural word-of-mouth
+- Lower-ticket or self-serve products
+
+**Characteristics:**
+- Referrer is an existing customer
+- One-time or limited rewards
+- Higher trust, lower volume
+
+### Affiliate Programs
+
+**Best for:**
+- Reaching audiences you don't have access to
+- Content creators, influencers, bloggers
+- Higher-ticket products that justify commissions
+
+**Characteristics:**
+- Affiliates may not be customers
+- Ongoing commission relationship
+- 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 rewards** (referrer only): Simpler, works for high-value products
+
+**Double-sided rewards** (both parties): Higher conversion, win-win framing
+
+**Tiered rewards**: Gamifies referral process, increases engagement
+
+**For examples and incentive sizing**: See [references/program-examples.md](references/program-examples.md)
+
+---
+
+## Program Optimization
+
+### Improving Referral Rate
+
+**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
+
+### A/B Tests to Run
+
+**Incentive tests:** Amount, type, single vs. double-sided, timing
+
+**Messaging tests:** Program description, CTA copy, landing page copy
+
+**Placement tests:** Where and when the referral prompt appears
+
+### 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
+
+**Program health:**
+- Active referrers (referred someone in last 30 days)
+- Referral conversion rate
+- Rewards earned/paid
+
+**Business impact:**
+- % of new customers from referrals
+- CAC via referral vs. other channels
+- LTV of referred customers
+- Referral program ROI
+
+### Typical Findings
+
+- 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
+- [ ] Create terms and conditions
+- [ ] Test complete referral flow
+
+### Launch
+- [ ] Announce to existing customers
+- [ ] Add in-app referral prompts
+- [ ] Update website with program details
+- [ ] Brief support team
+
+### Post-Launch (First 30 Days)
+- [ ] Review conversion funnel
+- [ ] Identify top referrers
+- [ ] Gather feedback
+- [ ] Fix friction points
+- [ ] Send reminder emails to non-referrers
+
+---
+
+## Email Sequences
+
+### Referral Program Launch
+
+```
+Subject: You can now earn [reward] for sharing [Product]
+
+We just launched our referral program!
+
+Share [Product] with friends and earn [reward] for each signup.
+They get [their reward] too.
+
+[Unique referral link]
+
+1. Share your link
+2. Friend signs up
+3. You both get [reward]
+```
+
+### Referral Nurture Sequence
+
+- Day 7: Remind about referral program
+- Day 30: "Know anyone who'd benefit?"
+- Day 60: Success story + referral prompt
+- After milestone: "You achieved [X]—know others who'd want this?"
+
+---
+
+## Affiliate Programs
+
+**For detailed affiliate program design, commission structures, recruitment, and tools**: See [references/affiliate-programs.md](references/affiliate-programs.md)
+
+---
+
+## Task-Specific Questions
+
+1. What type of program (referral, affiliate, or both)?
+2. What's your customer LTV and current CAC?
+3. Existing program or starting from scratch?
+4. What tools/platforms are you considering?
+5. What's your budget for rewards/commissions?
+6. Is your product naturally shareable?
+
+---
+
+## Tool Integrations
+
+For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for referral programs:
+
+| Tool | Best For | Guide |
+|------|----------|-------|
+| **Rewardful** | Stripe-native affiliate programs | [rewardful.md](../../tools/integrations/rewardful.md) |
+| **Tolt** | SaaS affiliate programs | [tolt.md](../../tools/integrations/tolt.md) |
+| **Mention Me** | Enterprise referral programs | [mention-me.md](../../tools/integrations/mention-me.md) |
+| **Dub.co** | Link tracking and attribution | [dub-co.md](../../tools/integrations/dub-co.md) |
+| **Stripe** | Payment processing (for commission tracking) | [stripe.md](../../tools/integrations/stripe.md) |
+
+---
+
+## Related Skills
+
+- **launch-strategy**: For launching referral program effectively
+- **email-sequence**: For referral nurture campaigns
+- **marketing-psychology**: For understanding referral motivation
+- **analytics-tracking**: For tracking referral attribution

package/src/skills-lib/referral-program/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "referral-program",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",
+      "expected_output": "Should check for product-marketing-context.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Distinguishes referral from affiliate",
+        "Designs the referral loop (trigger, share, convert, reward)",
+        "Recommends double-sided incentive structure",
+        "Suggests specific incentives for the price point",
+        "Includes launch checklist",
+        "Recommends tool integrations"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We have a referral program but only 5% of customers have ever referred someone. How do we increase participation?",
+      "expected_output": "Should apply the program optimization guidance. Should diagnose low participation: are customers aware of the program? Is the trigger point well-timed? Is the incentive compelling enough? Is sharing easy? Should recommend optimization tactics: better placement/visibility, timing referral asks at peak satisfaction moments, improving the incentive, simplifying the share mechanism, adding referral reminders in email and in-app. Should provide specific experiment ideas to test improvements.",
+      "assertions": [
+        "Applies program optimization guidance",
+        "Diagnoses potential causes of low participation",
+        "Checks awareness, timing, incentive, and friction",
+        "Recommends optimization tactics",
+        "Suggests timing referral asks at satisfaction moments",
+        "Provides experiment ideas"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "should we do referral or affiliate? we sell online courses for $199-499 and want to get other creators and influencers to promote us.",
+      "expected_output": "Should trigger on casual phrasing. Should apply the referral vs affiliate distinction clearly. For this use case (getting creators/influencers to promote), should recommend an affiliate program (not referral — affiliates are third-party promoters, not existing customers). Should apply the affiliate program section guidance: commission structure for digital products (typically 20-40% for courses), cookie duration, payout terms, affiliate onboarding. Should recommend affiliate platforms/tools appropriate for course creators.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Clearly distinguishes referral from affiliate",
+        "Recommends affiliate for this use case",
+        "Provides commission structure guidance for courses",
+        "Addresses cookie duration and payout terms",
+        "Recommends appropriate affiliate platforms"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "What incentive structure works best? We've been offering $10 off for referrers but it's not working. Our product is $29/month.",
+      "expected_output": "Should evaluate the current incentive: $10 off on a $29/month product is significant but only benefits the referrer (single-sided). Should recommend testing double-sided incentives (both parties get value). Should discuss incentive types: account credit, free months, feature upgrades, cash. Should apply the tiered incentive concept (increasing rewards for multiple referrals). Should provide specific alternative incentive structures to test. Should note that incentive alone may not be the problem — placement and timing matter too.",
+      "assertions": [
+        "Evaluates current incentive structure",
+        "Identifies as single-sided and recommends double-sided",
+        "Discusses multiple incentive types",
+        "Applies tiered incentive concept",
+        "Provides specific alternatives to test",
+        "Notes incentive may not be the only issue"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "How do we measure the success of our referral program? What metrics should we track?",
+      "expected_output": "Should apply the measuring success framework. Should define key metrics: participation rate (% of customers who refer), share rate (referrals sent per participant), conversion rate (referred visitors who become customers), viral coefficient (k-factor), customer acquisition cost via referral vs other channels, referred customer LTV vs organic customer LTV. Should recommend tracking tools and dashboards. Should provide benchmark ranges for each metric.",
+      "assertions": [
+        "Applies measuring success framework",
+        "Defines participation rate, share rate, conversion rate",
+        "Includes viral coefficient / k-factor",
+        "Compares referral CAC to other channels",
+        "Compares referred customer LTV to organic",
+        "Recommends tracking approach",
+        "Provides benchmark ranges"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Can you write the referral invitation emails? I need the email that goes out when someone shares their referral link.",
+      "expected_output": "Should recognize this overlaps with email writing. Should apply the referral email sequence section from the skill for referral-specific emails. However, for detailed email sequence design (multi-email nurture for referred users), should cross-reference the email-sequence skill. Should provide the referral invitation email but note that broader email sequence work is handled by email-sequence.",
+      "assertions": [
+        "Applies referral email section from the skill",
+        "Provides referral invitation email guidance",
+        "Cross-references email-sequence for broader email work",
+        "Provides specific referral email copy or template"
+      ],
+      "files": []
+    }
+  ]
+}

package/src/skills-lib/referral-program/references/affiliate-programs.md

@@ -0,0 +1,164 @@
+# Affiliate Program Design
+
+Detailed guidance for building and managing affiliate programs.
+
+## Contents
+- Commission Structures
+- Cookie Duration
+- Affiliate Recruitment
+- Affiliate Enablement
+- Tools & Platforms (Referral Program Tools, Affiliate Program Tools, Choosing a Tool)
+- Fraud Prevention (Common Referral Fraud, Prevention Measures)
+
+## Commission Structures
+
+**Percentage of sale:**
+- Standard: 10-30% of first sale or first year
+- Works for: E-commerce, SaaS with clear pricing
+- Example: "Earn 25% of every sale you refer"
+
+**Flat fee per action:**
+- Standard: $5-500 depending on value
+- Works for: Lead gen, trials, freemium
+- Example: "$50 for every qualified demo"
+
+**Recurring commission:**
+- Standard: 10-25% of recurring revenue
+- Works for: Subscription products
+- Example: "20% of subscription for 12 months"
+
+**Tiered commission:**
+- Works for: Motivating high performers
+- Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"
+
+---
+
+## Cookie Duration
+
+How long after click does affiliate get credit?
+
+| Duration | Use Case |
+|----------|----------|
+| 24 hours | High-volume, low-consideration purchases |
+| 7-14 days | Standard e-commerce |
+| 30 days | Standard SaaS/B2B |
+| 60-90 days | Long sales cycles, enterprise |
+| Lifetime | Premium affiliate relationships |
+
+---
+
+## Affiliate Recruitment
+
+### Where to find affiliates:
+- Existing customers who create content
+- Industry bloggers and reviewers
+- YouTubers in your niche
+- Newsletter writers
+- Complementary tool companies
+- Consultants and agencies
+
+### Outreach template:
+```
+Subject: Partnership opportunity — [Your Product]
+
+Hi [Name],
+
+I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.
+
+[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.
+
+We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].
+
+Would you be open to learning more?
+
+[Your name]
+```
+
+---
+
+## Affiliate Enablement
+
+Provide affiliates with:
+- [ ] Unique tracking links/codes
+- [ ] Product overview and key benefits
+- [ ] Target audience description
+- [ ] Comparison to competitors
+- [ ] Creative assets (logos, banners, images)
+- [ ] Sample copy and talking points
+- [ ] Case studies and testimonials
+- [ ] Demo access or free account
+- [ ] FAQ and objection handling
+- [ ] Payment terms and schedule
+
+---
+
+## Tools & Platforms
+
+### Referral Program Tools
+
+**Full-featured platforms:**
+- ReferralCandy — E-commerce focused
+- Ambassador — Enterprise referral programs
+- Friendbuy — E-commerce and subscription
+- GrowSurf — SaaS and tech companies
+- Mention Me — AI-powered referral marketing
+- Viral Loops — Template-based campaigns
+
+**Built-in options:**
+- Stripe (basic referral tracking)
+- HubSpot (CRM-integrated)
+- Segment (tracking and analytics)
+
+### Affiliate Program Tools
+
+**Affiliate networks:**
+- ShareASale — Large merchant network
+- Impact — Enterprise partnerships
+- PartnerStack — SaaS focused
+- Tapfiliate — Simple SaaS affiliate tracking
+- FirstPromoter — SaaS affiliate management
+
+**Self-hosted:**
+- Rewardful — Stripe-integrated affiliates
+- Refersion — E-commerce affiliates
+
+### Choosing a Tool
+
+Consider:
+- Integration with your payment system
+- Fraud detection capabilities
+- Payout management
+- Reporting and analytics
+- Customization options
+- Price vs. program scale
+
+---
+
+## Fraud Prevention
+
+### Common Referral Fraud
+- Self-referrals (creating fake accounts)
+- Referral rings (groups referring each other)
+- Coupon sites posting referral codes
+- Fake email addresses
+- VPN/device spoofing
+
+### Prevention Measures
+
+**Technical:**
+- Email verification required
+- Device fingerprinting
+- IP address monitoring
+- Delayed reward payout (after activation)
+- Minimum activity threshold
+
+**Policy:**
+- Clear terms of service
+- Maximum referrals per period
+- Reward clawback for refunds/chargebacks
+- Manual review for suspicious patterns
+
+**Structural:**
+- Require referred user to take meaningful action
+- Cap lifetime rewards
+- Pay rewards in product credit (less attractive to fraudsters)

package/src/skills-lib/referral-program/references/program-examples.md

@@ -0,0 +1,143 @@
+# Referral Program Examples
+
+Real-world examples of successful referral programs.
+
+## Contents
+- Dropbox (Classic)
+- Uber/Lyft
+- Morning Brew
+- Notion
+- Incentive Types Comparison
+- Incentive Sizing Framework
+- Viral Coefficient & Metrics (Key Metrics, Calculating Referral Program ROI)
+
+## Dropbox (Classic)
+
+**Program:** Give 500MB storage, get 500MB storage
+
+**Why it worked:**
+- Reward directly tied to product value
+- Low friction (just an email)
+- Both parties benefit equally
+- Gamified with progress tracking
+
+---
+
+## Uber/Lyft
+
+**Program:** Give $10 ride credit, get $10 when they ride
+
+**Why it worked:**
+- Immediate, clear value
+- Double-sided incentive
+- Easy to share (code/link)
+- Triggered at natural moments
+
+---
+
+## Morning Brew
+
+**Program:** Tiered rewards for subscriber referrals
+- 3 referrals: Newsletter stickers
+- 5 referrals: T-shirt
+- 10 referrals: Mug
+- 25 referrals: Hoodie
+
+**Why it worked:**
+- Gamification drives ongoing engagement
+- Physical rewards are shareable (more referrals)
+- Low cost relative to subscriber value
+- Built status/identity
+
+---
+
+## Notion
+
+**Program:** $10 credit per referral (education)
+
+**Why it worked:**
+- Targeted high-sharing audience (students)
+- Product naturally spreads in teams
+- Credit keeps users engaged
+
+---
+
+## Incentive Types Comparison
+
+| Type | Pros | Cons | Best For |
+|------|------|------|----------|
+| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
+| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
+| Free months | Clear value | May attract freebie-seekers | Subscription products |
+| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
+| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
+| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |
+
+---
+
+## Incentive Sizing Framework
+
+**Calculate your maximum incentive:**
+```
+Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC
+```
+
+**Example:**
+- LTV: $1,200
+- Gross margin: 70%
+- Target CAC: $200
+- Max reward: ($1,200 × 0.70) - $200 = $640
+
+**Typical referral rewards:**
+- B2C: $10-50 or 10-25% of first purchase
+- B2B SaaS: $50-500 or 1-3 months free
+- Enterprise: Higher, often custom
+
+---
+
+## Viral Coefficient & Metrics
+
+### Key Metrics
+
+**Viral coefficient (K-factor):**
+```
+K = Invitations × Conversion Rate
+
+K > 1 = Viral growth (each user brings more than 1 new user)
+K < 1 = Amplified growth (referrals supplement other acquisition)
+```
+
+**Example:**
+- Average customer sends 3 invitations
+- 15% of invitations convert
+- K = 3 × 0.15 = 0.45
+
+**Referral rate:**
+```
+Referral Rate = (Customers who refer) / (Total customers)
+```
+
+Benchmarks:
+- Good: 10-25% of customers refer
+- Great: 25-50%
+- Exceptional: 50%+
+
+**Referrals per referrer:**
+
+Benchmarks:
+- Average: 1-2 referrals per referrer
+- Good: 2-5
+- Exceptional: 5+
+
+### Calculating Referral Program ROI
+
+```
+Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs
+
+Program costs = Rewards paid + Tool costs + Management time
+```
+
+**Track separately:**
+- Cost per referred customer (CAC via referral)
+- LTV of referred customers (often higher than average)
+- Payback period for referral rewards