@stacksjs/defaults 0.75.108 → 0.75.110

package/ai/skills/stacks-marketing-onboarding/PLAYBOOK.md

@@ -0,0 +1,257 @@
+> Adapted playbook. The [shared Stacks workflow](../stacks-marketing/WORKFLOW.md) governs implementation, current facts, and authorization.
+
+
+# Onboarding CRO
+
+You are an expert in user onboarding and activation. Your goal is to help users reach their "aha moment" as quickly as possible and establish habits that lead to long-term retention.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+Read the established product context described in [the shared workflow](../stacks-marketing/WORKFLOW.md) before asking questions.
+
+Before providing recommendations, understand:
+
+1. **Product Context** - What type of product? B2B or B2C? Core value proposition?
+2. **Activation Definition** - What's the "aha moment"? What action indicates a user "gets it"?
+3. **Current State** - What happens after signup? Where do users drop off?
+
+---
+
+## Core Principles
+
+### 1. Time-to-Value Is Everything
+Remove every step between signup and experiencing core value. Design the **Minimum Path to Value (MPTV)** - the least number of steps to experience enough value to make a confident decision (see [references/minimum-path-to-value.md](references/minimum-path-to-value.md)).
+
+### 2. One Goal Per Session
+Focus first session on one successful outcome. Save advanced features for later.
+
+### 3. Do, Don't Show
+Interactive > Tutorial. Doing the thing > Learning about the thing.
+
+### 4. Progress Creates Motivation
+Show advancement. Celebrate completions. Make the path visible. (See stacks-marketing-onboarding psychology below for the mechanisms.)
+
+---
+
+## Onboarding Psychology
+
+The principles that make progress mechanics, checklists, and prompts actually work:
+
+- **Endowed Progress Effect** - people finish faster when progress is already started for them. A checklist that opens at "20% done" (a step pre-completed on their behalf) drives roughly **+40% completion** vs. starting at 0%. Give users a head start, don't make them start from nothing.
+- **Peak-End Rule** - users remember an experience by its most intense moment (the *peak*) and its *end*, not the average. Engineer a clear high point (a win, a wow, a celebration) and end each session on a positive note.
+- **Goldilocks Rule** - motivation peaks when a task is neither too easy nor too hard, but *just right* on the edge of ability. Tune early steps so they're achievable but not trivial.
+- **BJ Fogg Behavior Model** - a behavior happens only when **Motivation × Ability × Prompt** converge at the same moment. If a step isn't happening, one of the three is missing: raise motivation, make it easier (Ability), or add a better-timed Prompt.
+- **Mario Kart boosters & blockers** (Ramli John) - treat onboarding like a race track. Add **boosters** (accelerants: pre-filled data, templates, quick wins, celebrations) and remove **blockers** (friction: required fields, dead ends, confusing empty states). Speed users toward value and clear obstacles from the lane.
+
+## Onboarding Toolkit (10 Components)
+
+The components you assemble an onboarding experience from. Use the fewest that reach value:
+
+| Component | Purpose |
+|-----------|---------|
+| Welcome forms | Capture role/goal to personalize the path (keep short - Hick's Law) |
+| Initial screens | First-run screens that orient and point to one clear action |
+| Drip emails | Multi-touch nurture - **one concept per email**, don't overload |
+| Skippable tutorials | Optional guidance users can bypass - never trap them |
+| Videos | Show complex workflows visually |
+| Docs / help center | Self-serve reference for when users get stuck |
+| Onboarding calls | Human touch for complex or high-value accounts |
+| Data inputs | Getting the user's real data in so value feels "real" |
+| Checklists | Ordered, value-first steps with visible progress (see below) |
+| Empty states | Guided first-action opportunities, not dead ends (see below) |
+
+---
+
+## Defining Activation
+
+**Judge activation by lead→customer conversion + 90-day retention, not lead volume.** More signups mean nothing if they don't convert and stick.
+
+Choose an **activation model** (freemium, free trial, paid trial, money-back, consultation) before designing the flow - the model shapes the whole onboarding path. See [references/activation-models.md](references/activation-models.md) for the 5 models, the credit-card tradeoff, Model-Market Fit, and the Evernote-vs-Notion parable.
+
+### Find Your Aha Moment
+
+The action that correlates most strongly with retention:
+- What do retained users do that churned users don't?
+- What's the earliest indicator of future engagement?
+
+**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
+
+### Activation Metrics
+- % of signups who reach activation
+- Time to activation
+- Steps to activation
+- Activation by cohort/source
+
+---
+
+## Onboarding Flow Design
+
+### Immediate Post-Signup (First 30 Seconds)
+
+| 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" |
+
+**Whatever you choose:**
+- Clear single next action
+- No dead ends
+- Progress indication if multi-step
+
+### Onboarding Checklist Pattern
+
+**When to use:**
+- Multiple setup steps required
+- Product has several features to discover
+- Self-serve B2B products
+
+**Best practices:**
+- 3-7 items (not overwhelming)
+- 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
+
+**When to use:** Complex UI, features that aren't self-evident, power features users might miss
+
+**Best practices:**
+- Max 3-5 steps per tour
+- Dismissable at any time
+- Don't repeat for returning users
+
+---
+
+## Multi-Channel Onboarding
+
+### Email + In-App Coordination
+
+**Trigger-based emails:**
+- Welcome email (immediate)
+- Incomplete onboarding (24h, 72h)
+- Activation achieved (celebration + next step)
+- Feature discovery (days 3, 7, 14)
+
+**Email should:**
+- Reinforce in-app actions, not duplicate them
+- Drive back to product with specific CTA
+- Be personalized based on actions taken
+
+---
+
+## 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
+
+---
+
+## Measurement
+
+### Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| Activation rate | % reaching activation event |
+| Time to activation | How long to first value |
+| Onboarding completion | % completing setup |
+| Day 1/7/30 retention | Return rate by timeframe |
+
+### Funnel Analysis
+
+Track drop-off at each step:
+```
+Signup → Step 1 → Step 2 → Activation → Retention
+100%      80%       60%       40%         25%
+```
+
+Identify biggest drops and focus there.
+
+---
+
+## Output Format
+
+### Onboarding Audit
+For each issue: Finding → Impact → Recommendation → Priority
+
+### Onboarding Flow Design
+- Activation goal
+- Step-by-step flow
+- Checklist items (if applicable)
+- Empty state copy
+- Email sequence triggers
+- Metrics plan
+
+---
+
+## 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 |
+
+---
+
+## Experiment Ideas
+
+When recommending experiments, consider tests for:
+- Flow simplification (step count, ordering)
+- Progress and motivation mechanics
+- Personalization by role or goal
+- Support and help availability
+
+**For comprehensive experiment ideas**: See [references/experiments.md](references/experiments.md)
+
+---
+
+## References
+
+- **[references/minimum-path-to-value.md](references/minimum-path-to-value.md)** - MPTV, Hick's Law, the inventory→remove→reconstruct process, abandonment benchmarks (40-60% after one session; 75-80% within day one), and patterns (Stripe, Calendly, Notion).
+- **[references/activation-models.md](references/activation-models.md)** - the 5 activation models, credit-card tradeoff, Model-Market Fit, Evernote vs. Notion.
+- **[references/experiments.md](references/experiments.md)** - comprehensive A/B test and experiment ideas.
+
+---
+
+## Task-Specific Questions
+
+1. What action most correlates with retention?
+2. What happens immediately after signup?
+3. Where do users currently drop off?
+4. What's your activation rate target?
+5. Do you have cohort analysis on successful vs. churned users?
+
+---
+
+## Related Skills
+
+- **stacks-marketing-signup**: For optimizing the signup before onboarding
+- **stacks-marketing-emails**: For onboarding email series
+- **stacks-marketing-paywalls**: For converting to paid during/after onboarding
+- **stacks-marketing-ab-testing**: For testing onboarding changes

package/ai/skills/stacks-marketing-onboarding/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: stacks-marketing-onboarding
+description: Use when the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Covers marketing planning and its Stacks implementation.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Marketing Onboarding
+
+Read [the shared Stacks workflow](../stacks-marketing/WORKFLOW.md), then
+[PLAYBOOK.md](PLAYBOOK.md) before doing this task. Load the supporting references
+only for the branch the playbook routes to.
+
+This ports `onboarding` from
+[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills/tree/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/skills/onboarding).
+[NOTICE.md](NOTICE.md) records the snapshot and [LICENSE](LICENSE) retains the
+upstream MIT notice.
+
+## Stacks integration
+
+Keep marketing recommendations distinct from application API facts. Use the
+framework skill for any model, action, route, stx page, campaign job, or payment
+change. Use the user's existing brief and authorization; a playbook example
+does not supply a product fact or authorize sending, spending, or publishing.
+
+Platform limits and benchmarks in the snapshot need current primary-source
+verification before use. Return the requested artifact with consequential
+assumptions and evidence, then verify any implementation through its real
+behavior. Use TypeScript and Bun for executable helpers.

package/ai/skills/stacks-marketing-onboarding/evals/evals.json

@@ -0,0 +1,108 @@
+{
+  "skill_name": "stacks-marketing-onboarding",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me optimize our onboarding flow. We have a project management tool and only 30% of trial users create their first project within the first week. We need to get them to value faster.",
+      "expected_output": "Should check for product-marketing.md first. Should start by defining the activation/aha moment - in this case, creating a first project. Should evaluate the current time-to-value and identify friction points. Should recommend an onboarding flow approach (product-first, guided setup, or value-first). Should apply the checklist pattern (3-7 items for onboarding completion). Should address empty states as opportunities to guide users. Should provide experiment ideas for testing improvements. Should include measurement metrics.",
+      "assertions": [
+        "Checks for product-marketing.md",
+        "Defines the activation/aha moment",
+        "Evaluates time-to-value",
+        "Recommends onboarding flow approach",
+        "Applies checklist pattern with 3-7 items",
+        "Addresses empty states as opportunities",
+        "Provides experiment ideas",
+        "Includes measurement metrics"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "What should our onboarding checklist include? We're a design collaboration tool. Users need to upload a design, invite a team member, and leave a comment to get full value.",
+      "expected_output": "Should apply the checklist pattern. Should include the 3 stated activation actions (upload design, invite team, leave comment). Should recommend 3-7 total items ordered by increasing commitment. Should suggest starting with the quickest win to build momentum. Should recommend progress indicators and completion rewards. Should address what happens when users skip items. Should provide specific UX recommendations for the checklist implementation.",
+      "assertions": [
+        "Applies checklist pattern",
+        "Includes the 3 stated activation actions",
+        "Limits to 3-7 total items",
+        "Orders by increasing commitment",
+        "Starts with quickest win",
+        "Recommends progress indicators",
+        "Addresses skipped items",
+        "Provides UX recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "our users sign up but then never come back. like 50% don't even log in a second time. what do we do?",
+      "expected_output": "Should trigger on casual phrasing. Should address this as a stalled users problem. Should apply the handling stalled users framework: identify drop-off points, re-engagement triggers, multi-channel outreach (email, in-app, push). Should investigate root causes: is the first-run experience too complex? Is value not immediately apparent? Is the setup too long? Should recommend immediate improvements to the first session experience. Should suggest multi-channel onboarding (email sequences to bring them back). Should cross-reference emails for re-engagement emails.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Applies stalled users framework",
+        "Identifies potential root causes for drop-off",
+        "Recommends first-session experience improvements",
+        "Suggests multi-channel onboarding",
+        "Cross-references emails for re-engagement",
+        "Provides specific re-engagement triggers"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "How do we handle the empty state when a new user first logs in? Right now they just see a blank dashboard.",
+      "expected_output": "Should apply the empty states as opportunities guidance. Should recommend turning the blank dashboard into a guided experience: sample data to show what the product looks like populated, a clear first action CTA, contextual tips, or a quick-start wizard. Should provide specific recommendations for empty state design: what to show, what action to prompt, how to reduce the 'blank canvas paralysis.' Should reference patterns by product type if applicable.",
+      "assertions": [
+        "Applies empty states as opportunities guidance",
+        "Recommends alternatives to blank dashboard",
+        "Suggests sample data or templates",
+        "Provides clear first action CTA",
+        "Addresses blank canvas paralysis",
+        "Provides specific empty state design recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Should we use tooltips, a product tour, or a setup wizard for onboarding? What works best?",
+      "expected_output": "Should apply the tooltips/guided tours guidance. Should compare the approaches: tooltips (contextual, on-demand, less intrusive), product tours (guided walkthrough, can overwhelm), setup wizards (structured, ensures key setup steps). Should recommend based on product complexity and onboarding goals. Should note that the best approach often combines elements. Should provide best practices for each: tooltip fatigue avoidance, tour length limits, wizard step count. Should recommend testing different approaches.",
+      "assertions": [
+        "Compares tooltips, product tours, and setup wizards",
+        "Explains when each works best",
+        "Notes that combination approaches often work",
+        "Provides best practices for each",
+        "Addresses tooltip fatigue and tour length",
+        "Recommends testing different approaches"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Our signup form has 8 fields and people keep dropping off. Can you help us fix the signup flow?",
+      "expected_output": "Should recognize this is a signup flow optimization task, not post-signup onboarding. Should defer to or cross-reference the signup skill, which handles signup form optimization, field reduction, and registration flow design. Onboarding-cro covers what happens after signup. Should make this distinction clear.",
+      "assertions": [
+        "Recognizes this as signup flow optimization, not onboarding",
+        "References or defers to signup skill",
+        "Explains that onboarding covers post-signup",
+        "Does not attempt signup form redesign using onboarding patterns"
+      ],
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "We're launching a new B2B analytics product and can't decide how to let people try it. Should we do a free tier, a free trial, require a credit card, or something else? And once they're in, how do we make sure they actually reach value fast?",
+      "expected_output": "Should walk through the 5 activation models (freemium, free trial with 3/7/14/30-day options, paid trial, money-back guarantee, consultation/Superhuman-style) and help choose based on Model-Market Fit (Balfour - the market dictates the model). Should explain the credit-card tradeoff: requiring a card cuts signups 50-70% but converts 2-3× better. Should reference the Evernote-vs-Notion lesson (hook then limit vs. give away too much). Should then design the Minimum Path to Value (MPTV) - the least steps to enough value to decide - grounded in Hick's Law, using inventory → remove → reconstruct. Should cite abandonment reality (40-60% abandon after one session; 75-80% within the first day). May reference psychology mechanisms (Endowed Progress Effect, Peak-End, BJ Fogg, Mario Kart boosters/blockers). Should point to the activation-models and minimum-path-to-value references.",
+      "assertions": [
+        "Presents the 5 activation models",
+        "Applies Model-Market Fit to the choice",
+        "Explains the credit-card tradeoff (cuts signups 50-70%, 2-3x conversion)",
+        "References Evernote-vs-Notion hook-then-limit lesson",
+        "Designs a Minimum Path to Value grounded in Hick's Law",
+        "Uses inventory -> remove -> reconstruct process",
+        "Cites first-session/first-day abandonment stats",
+        "Points to activation-models.md and minimum-path-to-value.md references"
+      ],
+      "files": []
+    }
+  ]
+}

package/ai/skills/stacks-marketing-onboarding/references/activation-models.md

@@ -0,0 +1,57 @@
+# Activation Models
+
+The activation model is *how* you let a user experience value before they pay. It shapes signup volume, conversion, and the entire onboarding path. Pick the model before you design the flow.
+
+## The 5 activation models
+
+### 1. Freemium
+A free tier that never expires, with paid tiers for more capacity or features.
+
+- Best when: the free tier delivers real value *and* naturally hits limits that motivate upgrading.
+- Risk: give away too much and users never need to pay (see Evernote below).
+
+### 2. Free trial
+Full (or near-full) access for a fixed window: **3, 7, 14, or 30 days**.
+
+- Shorter trials create urgency and force faster time-to-value; longer trials suit complex products with longer setup.
+- **Credit-card requirement is the key lever**: requiring a card up front **cuts signups by 50-70%**, but the users who do sign up **convert 2-3× better**. Fewer, higher-intent leads vs. more, lower-intent leads - choose based on your funnel goals.
+
+### 3. Paid trial
+A low-cost paid entry, typically **$7-10 for 7 days**.
+
+- Filters out tire-kickers while lowering the barrier vs. full price.
+- Signals seriousness on both sides and pre-collects payment details.
+
+### 4. Money-back guarantee
+Charge full price up front, with a no-questions refund window.
+
+- Removes purchase risk without giving anything away for free.
+- Works when the product delivers value quickly enough to beat the refund window.
+
+### 5. Consultation / white-glove
+A human conversation (demo, call, or hands-on setup) gates access - the **Superhuman** model.
+
+- Best for high-touch, high-price, or complex products where a human ensures the user reaches value.
+- Doesn't scale cheaply, but converts and retains well when done right.
+
+## Model-Market Fit
+
+**Model-Market Fit (Brian Balfour): "your market dictates your model."**
+
+You don't get to freely choose your activation model - your market chooses it for you. Price point, buyer sophistication, sales complexity, time-to-value, and competitor norms all constrain what will work. A self-serve $20/mo tool and a $50k enterprise platform cannot use the same model. Match the model to the market before optimizing the onboarding inside it.
+
+## The Evernote vs. Notion parable
+
+Two lessons on how much to give away:
+
+- **Evernote - gave away too much free.** The free tier was generous enough that most users never needed to upgrade. Free was a destination, not a doorway. Growth without matching monetization.
+- **Notion - hook, then limit.** Let users experience real value, then hit meaningful limits (blocks, members, features) that create a natural, well-timed reason to pay.
+
+The principle: **the free experience should hook, not satisfy.** Give enough value to prove the product and build the habit - but structure the limits so that continued value requires upgrading.
+
+## Choosing
+
+1. Start from your market (Model-Market Fit), not your preference.
+2. Decide the card-vs-no-card tradeoff explicitly: volume of leads vs. quality of leads.
+3. Design the free/trial experience to hook and then limit - never to fully satisfy.
+4. Whatever the model, the onboarding inside it still needs the shortest possible path to value (see [minimum-path-to-value.md](minimum-path-to-value.md)).