wizz-method 1.4.0 → 1.5.0

package/src/skills-lib/popup-cro/SKILL.md

@@ -16,423 +16,22 @@ If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-
 
 Before providing recommendations, understand:
 
-1. **Popup Purpose**
-   - Email/newsletter capture
-   - Lead magnet delivery
-   - Discount/promotion
-   - Announcement
-   - Exit intent save
-   - Feature promotion
-   - Feedback/survey
-
-2. **Current State**
-   - Existing popup performance?
-   - What triggers are used?
-   - User complaints or feedback?
-   - Mobile experience?
-
-3. **Traffic Context**
-   - Traffic sources (paid, organic, direct)
-   - New vs. returning visitors
-   - Page types where shown
-
----
+1. **Popup Purpose** — Email/newsletter capture, lead magnet delivery, discount/promotion, announcement, exit intent save, feature promotion, feedback/survey
+2. **Current State** — Existing popup performance? What triggers are used? User complaints or feedback? Mobile experience?
+3. **Traffic Context** — Traffic sources (paid, organic, direct), new vs. returning visitors, page types where shown
 
 ## Core Principles
 
-### 1. Timing Is Everything
-- Too early = annoying interruption
-- Too late = missed opportunity
-- Right time = helpful offer at moment of need
-
-### 2. Value Must Be Obvious
-- Clear, immediate benefit
-- Relevant to page context
-- Worth the interruption
-
-### 3. Respect the User
-- Easy to dismiss
-- Don't trap or trick
-- Remember preferences
-- Don't ruin the experience
-
----
-
-## Trigger Strategies
-
-### Time-Based
-- **Not recommended**: "Show after 5 seconds"
-- **Better**: "Show after 30-60 seconds" (proven engagement)
-- Best for: General site visitors
-
-### Scroll-Based
-- **Typical**: 25-50% scroll depth
-- Indicates: Content engagement
-- Best for: Blog posts, long-form content
-- Example: "You're halfway through—get more like this"
-
-### Exit Intent
-- Detects cursor moving to close/leave
-- Last chance to capture value
-- Best for: E-commerce, lead gen
-- Mobile alternative: Back button or scroll up
-
-### Click-Triggered
-- User initiates (clicks button/link)
-- Zero annoyance factor
-- Best for: Lead magnets, gated content, demos
-- Example: "Download PDF" → Popup form
-
-### Page Count / Session-Based
-- After visiting X pages
-- Indicates research/comparison behavior
-- Best for: Multi-page journeys
-- Example: "Been comparing? Here's a summary..."
-
-### Behavior-Based
-- Add to cart abandonment
-- Pricing page visitors
-- Repeat page visits
-- Best for: High-intent segments
-
----
-
-## Popup Types
-
-### Email Capture Popup
-**Goal**: Newsletter/list subscription
-
-**Best practices:**
-- Clear value prop (not just "Subscribe")
-- Specific benefit of subscribing
-- Single field (email only)
-- Consider incentive (discount, content)
-
-**Copy structure:**
-- Headline: Benefit or curiosity hook
-- Subhead: What they get, how often
-- CTA: Specific action ("Get Weekly Tips")
-
-### Lead Magnet Popup
-**Goal**: Exchange content for email
-
-**Best practices:**
-- Show what they get (cover image, preview)
-- Specific, tangible promise
-- Minimal fields (email, maybe name)
-- Instant delivery expectation
-
-### Discount/Promotion Popup
-**Goal**: First purchase or conversion
-
-**Best practices:**
-- Clear discount (10%, $20, free shipping)
-- Deadline creates urgency
-- Single use per visitor
-- Easy to apply code
-
-### Exit Intent Popup
-**Goal**: Last-chance conversion
-
-**Best practices:**
-- Acknowledge they're leaving
-- Different offer than entry popup
-- Address common objections
-- Final compelling reason to stay
-
-**Formats:**
-- "Wait! Before you go..."
-- "Forget something?"
-- "Get 10% off your first order"
-- "Questions? Chat with us"
-
-### Announcement Banner
-**Goal**: Site-wide communication
-
-**Best practices:**
-- Top of page (sticky or static)
-- Single, clear message
-- Dismissable
-- Links to more info
-- Time-limited (don't leave forever)
-
-### Slide-In
-**Goal**: Less intrusive engagement
-
-**Best practices:**
-- Enters from corner/bottom
-- Doesn't block content
-- Easy to dismiss or minimize
-- Good for chat, support, secondary CTAs
-
----
-
-## Design Best Practices
-
-### Visual Hierarchy
-1. Headline (largest, first seen)
-2. Value prop/offer (clear benefit)
-3. Form/CTA (obvious action)
-4. Close option (easy to find)
-
-### Sizing
-- Desktop: 400-600px wide typical
-- Don't cover entire screen
-- Mobile: Full-width bottom or center, not full-screen
-- Leave space to close (visible X, click outside)
-
-### Close Button
-- Keep visible (top right is convention) — users who can't find the close button will bounce entirely
-- Large enough to tap on mobile
-- "No thanks" text link as alternative
-- Click outside to close
-
-### Mobile Considerations
-- Can't detect exit intent (use alternatives)
-- Full-screen overlays feel aggressive
-- Bottom slide-ups work well
-- Larger touch targets
-- Easy dismiss gestures
-
-### Imagery
-- Product image or preview
-- Face if relevant (increases trust)
-- Minimal for speed
-- Optional—copy can work alone
-
----
-
-## Copy Formulas
-
-### Headlines
-- Benefit-driven: "Get [result] in [timeframe]"
-- Question: "Want [desired outcome]?"
-- Command: "Don't miss [thing]"
-- Social proof: "Join [X] people who..."
-- Curiosity: "The one thing [audience] always get wrong about [topic]"
-
-### Subheadlines
-- Expand on the promise
-- Address objection ("No spam, ever")
-- Set expectations ("Weekly tips in 5 min")
-
-### CTA Buttons
-- First person works: "Get My Discount" vs "Get Your Discount"
-- Specific over generic: "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
-
-### Frequency Capping
-- Show maximum once per session
-- Remember dismissals (cookie/localStorage)
-- 7-30 days before showing again
-- Respect user choice
-
-### Audience Targeting
-- New vs. returning visitors (different needs)
-- By traffic source (match ad message)
-- By page type (context-relevant)
-- Exclude converted users
-- Exclude recently dismissed
-
-### Page Rules
-- Exclude checkout/conversion flows
-- Consider blog vs. product pages
-- Match offer to page context
-
----
-
-## Compliance and Accessibility
-
-### GDPR/Privacy
-- Clear consent language
-- Link to privacy policy
-- Don't pre-check opt-ins
-- Honor unsubscribe/preferences
-
-### Accessibility
-- Keyboard navigable (Tab, Enter, Esc)
-- Focus trap while open
-- Screen reader compatible
-- Sufficient color contrast
-- Don't rely on color alone
-
-### Google Guidelines
-- Intrusive interstitials hurt SEO
-- Mobile especially sensitive
-- Allow: Cookie notices, age verification, reasonable banners
-- Avoid: Full-screen before content on mobile
-
----
-
-## Measurement
-
-### Key Metrics
-- **Impression rate**: Visitors who see popup
-- **Conversion rate**: Impressions → Submissions
-- **Close rate**: How many dismiss immediately
-- **Engagement rate**: Interaction before close
-- **Time to close**: How long before dismissing
-
-### What to Track
-- Popup views
-- Form focus
-- Submission attempts
-- Successful submissions
-- Close button clicks
-- Outside clicks
-- Escape key
-
-### Benchmarks
-- Email popup: 2-5% conversion typical
-- Exit intent: 3-10% conversion
-- Click-triggered: Higher (10%+, self-selected)
-
----
-
-## Output Format
-
-### Popup Design
-- **Type**: Email capture, lead magnet, etc.
-- **Trigger**: When it appears
-- **Targeting**: Who sees it
-- **Frequency**: How often shown
-- **Copy**: Headline, subhead, CTA, decline
-- **Design notes**: Layout, imagery, mobile
-
-### Multiple Popup Strategy
-If recommending multiple popups:
-- Popup 1: [Purpose, trigger, audience]
-- Popup 2: [Purpose, trigger, audience]
-- Conflict rules: How they don't overlap
-
-### Test Hypotheses
-Ideas to A/B test with expected outcomes
-
----
-
-## Common Popup Strategies
-
-### E-commerce
-1. Entry/scroll: First-purchase discount
-2. Exit intent: Bigger discount or reminder
-3. Cart abandonment: Complete your order
-
-### B2B SaaS
-1. Click-triggered: Demo request, lead magnets
-2. Scroll: Newsletter/blog subscription
-3. Exit intent: Trial reminder or content offer
-
-### Content/Media
-1. Scroll-based: Newsletter after engagement
-2. Page count: Subscribe after multiple visits
-3. Exit intent: Don't miss future content
-
-### Lead Generation
-1. Time-delayed: General list building
-2. Click-triggered: Specific lead magnets
-3. Exit intent: Final capture attempt
-
----
-
-## Experiment Ideas
+1. **Timing Is Everything** — too early is an annoying interruption, too late is a missed opportunity; the right time is a helpful offer at the moment of need.
+2. **Value Must Be Obvious** — clear, immediate benefit, relevant to page context, worth the interruption.
+3. **Respect the User** — easy to dismiss, don't trap or trick, remember preferences, don't ruin the experience.
 
-### Placement & Format Experiments
+## References (load on demand)
 
-**Banner Variations**
-- Top bar vs. banner below header
-- Sticky banner vs. static banner
-- Full-width vs. contained banner
-- Banner with countdown timer vs. without
-
-**Popup Formats**
-- Center modal vs. slide-in from corner
-- Full-screen overlay vs. smaller modal
-- Bottom bar vs. corner popup
-- Top announcements vs. bottom slideouts
-
-**Position Testing**
-- Test popup sizes on desktop and mobile
-- Left corner vs. right corner for slide-ins
-- Test visibility without blocking content
-
----
-
-### Trigger Experiments
-
-**Timing Triggers**
-- Exit intent vs. 30-second delay vs. 50% scroll depth
-- Test optimal time delay (10s vs. 30s vs. 60s)
-- Test scroll depth percentage (25% vs. 50% vs. 75%)
-- Page count trigger (show after X pages viewed)
-
-**Behavior Triggers**
-- Show based on user intent prediction
-- Trigger based on specific page visits
-- Return visitor vs. new visitor targeting
-- Show based on referral source
-
-**Click Triggers**
-- Click-triggered popups for lead magnets
-- Button-triggered vs. link-triggered modals
-- Test in-content triggers vs. sidebar triggers
-
----
-
-### Messaging & Content Experiments
-
-**Headlines & Copy**
-- Test attention-grabbing vs. informational headlines
-- "Limited-time offer" vs. "New feature alert" messaging
-- Urgency-focused copy vs. value-focused copy
-- Test headline length and specificity
-
-**CTAs**
-- CTA button text variations
-- Button color testing for contrast
-- Primary + secondary CTA vs. single CTA
-- Test decline text (friendly vs. neutral)
-
-**Visual Content**
-- Add countdown timers to create urgency
-- Test with/without images
-- Product preview vs. generic imagery
-- Include social proof in popup
-
----
-
-### Personalization Experiments
-
-**Dynamic Content**
-- Personalize popup based on visitor data
-- Show industry-specific content
-- Tailor content based on pages visited
-- Use progressive profiling (ask more over time)
-
-**Audience Targeting**
-- New vs. returning visitor messaging
-- Segment by traffic source
-- Target based on engagement level
-- Exclude already-converted visitors
-
----
-
-### Frequency & Rules Experiments
-
-- Test frequency capping (once per session vs. once per week)
-- Cool-down period after dismissal
-- Test different dismiss behaviors
-- Show escalating offers over multiple visits
-
----
+- `references/triggers-and-popup-types.md` — the 6 trigger mechanisms (time, scroll, exit intent, click, page count, behavior) and the 6 popup formats (email capture, lead magnet, discount, exit intent, announcement banner, slide-in) with best practices for each. Load when choosing what to build and how it should fire.
+- `references/design-copy-compliance.md` — visual hierarchy, sizing, close button, mobile, and imagery guidance; headline/subhead/CTA/decline copy formulas; GDPR, accessibility, and Google interstitial guidelines. Load when writing the actual popup and checking it's compliant before shipping.
+- `references/rules-measurement-output.md` — frequency capping and audience/page targeting rules; key metrics and benchmarks to track; the output format for a popup design deliverable; proven strategy patterns by vertical (e-commerce, B2B SaaS, content/media, lead gen). Load when finalizing rules, defining measurement, or formatting the recommendation.
+- `references/experiments.md` — a full experiment backlog (placement/format, triggers, messaging, personalization, frequency) for A/B testing. Load when the deliverable needs a test plan.
 
 ## Task-Specific Questions
 
@@ -443,8 +42,6 @@ Ideas to A/B test with expected outcomes
 5. Are there compliance requirements (GDPR, etc.)?
 6. Mobile vs. desktop traffic split?
 
----
-
 ## Related Skills
 
 - **form-cro**: For optimizing the form inside the popup

package/src/skills-lib/popup-cro/references/design-copy-compliance.md

@@ -0,0 +1,81 @@
+# Design, Copy, and Compliance
+
+Load this file when writing the actual popup copy, laying out the design, or checking GDPR/accessibility/SEO requirements before shipping.
+
+## Design Best Practices
+
+### Visual Hierarchy
+1. Headline (largest, first seen)
+2. Value prop/offer (clear benefit)
+3. Form/CTA (obvious action)
+4. Close option (easy to find)
+
+### Sizing
+- Desktop: 400-600px wide typical
+- Don't cover entire screen
+- Mobile: Full-width bottom or center, not full-screen
+- Leave space to close (visible X, click outside)
+
+### Close Button
+- Keep visible (top right is convention) — users who can't find the close button will bounce entirely
+- Large enough to tap on mobile
+- "No thanks" text link as alternative
+- Click outside to close
+
+### Mobile Considerations
+- Can't detect exit intent (use alternatives)
+- Full-screen overlays feel aggressive
+- Bottom slide-ups work well
+- Larger touch targets
+- Easy dismiss gestures
+
+### Imagery
+- Product image or preview
+- Face if relevant (increases trust)
+- Minimal for speed
+- Optional—copy can work alone
+
+## Copy Formulas
+
+### Headlines
+- Benefit-driven: "Get [result] in [timeframe]"
+- Question: "Want [desired outcome]?"
+- Command: "Don't miss [thing]"
+- Social proof: "Join [X] people who..."
+- Curiosity: "The one thing [audience] always get wrong about [topic]"
+
+### Subheadlines
+- Expand on the promise
+- Address objection ("No spam, ever")
+- Set expectations ("Weekly tips in 5 min")
+
+### CTA Buttons
+- First person works: "Get My Discount" vs "Get Your Discount"
+- Specific over generic: "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"
+
+## Compliance and Accessibility
+
+### GDPR/Privacy
+- Clear consent language
+- Link to privacy policy
+- Don't pre-check opt-ins
+- Honor unsubscribe/preferences
+
+### Accessibility
+- Keyboard navigable (Tab, Enter, Esc)
+- Focus trap while open
+- Screen reader compatible
+- Sufficient color contrast
+- Don't rely on color alone
+
+### Google Guidelines
+- Intrusive interstitials hurt SEO
+- Mobile especially sensitive
+- Allow: Cookie notices, age verification, reasonable banners
+- Avoid: Full-screen before content on mobile

package/src/skills-lib/popup-cro/references/experiments.md

@@ -0,0 +1,82 @@
+# Experiment Ideas
+
+Load this file when the deliverable includes a test plan / A/B test backlog for a popup.
+
+## Placement & Format Experiments
+
+**Banner Variations**
+- Top bar vs. banner below header
+- Sticky banner vs. static banner
+- Full-width vs. contained banner
+- Banner with countdown timer vs. without
+
+**Popup Formats**
+- Center modal vs. slide-in from corner
+- Full-screen overlay vs. smaller modal
+- Bottom bar vs. corner popup
+- Top announcements vs. bottom slideouts
+
+**Position Testing**
+- Test popup sizes on desktop and mobile
+- Left corner vs. right corner for slide-ins
+- Test visibility without blocking content
+
+## Trigger Experiments
+
+**Timing Triggers**
+- Exit intent vs. 30-second delay vs. 50% scroll depth
+- Test optimal time delay (10s vs. 30s vs. 60s)
+- Test scroll depth percentage (25% vs. 50% vs. 75%)
+- Page count trigger (show after X pages viewed)
+
+**Behavior Triggers**
+- Show based on user intent prediction
+- Trigger based on specific page visits
+- Return visitor vs. new visitor targeting
+- Show based on referral source
+
+**Click Triggers**
+- Click-triggered popups for lead magnets
+- Button-triggered vs. link-triggered modals
+- Test in-content triggers vs. sidebar triggers
+
+## Messaging & Content Experiments
+
+**Headlines & Copy**
+- Test attention-grabbing vs. informational headlines
+- "Limited-time offer" vs. "New feature alert" messaging
+- Urgency-focused copy vs. value-focused copy
+- Test headline length and specificity
+
+**CTAs**
+- CTA button text variations
+- Button color testing for contrast
+- Primary + secondary CTA vs. single CTA
+- Test decline text (friendly vs. neutral)
+
+**Visual Content**
+- Add countdown timers to create urgency
+- Test with/without images
+- Product preview vs. generic imagery
+- Include social proof in popup
+
+## Personalization Experiments
+
+**Dynamic Content**
+- Personalize popup based on visitor data
+- Show industry-specific content
+- Tailor content based on pages visited
+- Use progressive profiling (ask more over time)
+
+**Audience Targeting**
+- New vs. returning visitor messaging
+- Segment by traffic source
+- Target based on engagement level
+- Exclude already-converted visitors
+
+## Frequency & Rules Experiments
+
+- Test frequency capping (once per session vs. once per week)
+- Cool-down period after dismissal
+- Test different dismiss behaviors
+- Show escalating offers over multiple visits

package/src/skills-lib/popup-cro/references/rules-measurement-output.md

@@ -0,0 +1,87 @@
+# Frequency Rules, Measurement, Output Format, and Common Strategies
+
+Load this file when finalizing frequency/targeting rules, defining what to measure, formatting the deliverable, or picking a proven strategy pattern for a specific vertical (e-commerce, B2B SaaS, content/media, lead gen).
+
+## Frequency and Rules
+
+### Frequency Capping
+- Show maximum once per session
+- Remember dismissals (cookie/localStorage)
+- 7-30 days before showing again
+- Respect user choice
+
+### Audience Targeting
+- New vs. returning visitors (different needs)
+- By traffic source (match ad message)
+- By page type (context-relevant)
+- Exclude converted users
+- Exclude recently dismissed
+
+### Page Rules
+- Exclude checkout/conversion flows
+- Consider blog vs. product pages
+- Match offer to page context
+
+## Measurement
+
+### Key Metrics
+- **Impression rate**: Visitors who see popup
+- **Conversion rate**: Impressions → Submissions
+- **Close rate**: How many dismiss immediately
+- **Engagement rate**: Interaction before close
+- **Time to close**: How long before dismissing
+
+### What to Track
+- Popup views
+- Form focus
+- Submission attempts
+- Successful submissions
+- Close button clicks
+- Outside clicks
+- Escape key
+
+### Benchmarks
+- Email popup: 2-5% conversion typical
+- Exit intent: 3-10% conversion
+- Click-triggered: Higher (10%+, self-selected)
+
+## Output Format
+
+### Popup Design
+- **Type**: Email capture, lead magnet, etc.
+- **Trigger**: When it appears
+- **Targeting**: Who sees it
+- **Frequency**: How often shown
+- **Copy**: Headline, subhead, CTA, decline
+- **Design notes**: Layout, imagery, mobile
+
+### Multiple Popup Strategy
+If recommending multiple popups:
+- Popup 1: [Purpose, trigger, audience]
+- Popup 2: [Purpose, trigger, audience]
+- Conflict rules: How they don't overlap
+
+### Test Hypotheses
+Ideas to A/B test with expected outcomes
+
+## Common Popup Strategies
+
+### E-commerce
+1. Entry/scroll: First-purchase discount
+2. Exit intent: Bigger discount or reminder
+3. Cart abandonment: Complete your order
+
+### B2B SaaS
+1. Click-triggered: Demo request, lead magnets
+2. Scroll: Newsletter/blog subscription
+3. Exit intent: Trial reminder or content offer
+
+### Content/Media
+1. Scroll-based: Newsletter after engagement
+2. Page count: Subscribe after multiple visits
+3. Exit intent: Don't miss future content
+
+### Lead Generation
+1. Time-delayed: General list building
+2. Click-triggered: Specific lead magnets
+3. Exit intent: Final capture attempt