v2.0.0 to v2.0.0

17 added, 19 removed. Audit A to A.

---

name: suede-onboarding

description: "Suede-affiliated onboarding and activation strategy for first-run sequencing, empty states, setup checklists, activation milestones, time to value, and retention-linked measurement. Use when users sign up but fail to reach first value or the product needs a new first-session flow. NOT FOR: registration optimization (use suede-signup), lifecycle email sequences (use suede-emails), or monetization prompts (use suede-paywalls)."

metadata:

version: 2.0.0

---

# Suede Onboarding and Activation

Suede designs onboarding around verified first value and retention-linked activation, not decorative checklists or forced engagement. Define the activation evidence, remove unnecessary friction, sequence the first session, and instrument the path before claiming an "aha moment."

## Initial Assessment

**Check for product marketing context first:**

If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

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?

+ 3. **Current State** - What happens after signup? Where do users drop off? What activation rate are you targeting, and is there cohort analysis separating retained from churned users?

---

## Core Principles

### 1. Time-to-Value Is Everything

Remove every step between signup and experiencing core value.

### 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.

+ ### Defaults to Refuse

+ Named cliches this skill does not produce, however well they demo:

+ - The modal product tour that runs before the user has done anything in the product.

+ - The "Welcome! Let's get started" interstitial that sits between the user and the first action.

+ - The checklist item that is a settings toggle rather than a value action.

---

## Defining Activation

### 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

+ - Progress bar/completion % — only where the remaining steps are the activation path

+ - Celebration on completion — on the activation event, not on a two-step setup

- 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

+ Emit these headings verbatim, in this order:

+ **Activation Goal** — the event, plus the retention evidence behind it or "unverified"

+ **Flow** — one entry per step, each carrying: trigger, user action, success signal, drop-off measurement

+ **Checklist Items** — 3-7 value actions (omit the heading if no checklist)

+ **Empty State Copy** — per surface

+ **Email Triggers** — event and delay for each

+ **Metrics Plan** — activation rate, time to activation, per-step drop-off

---

## 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)

- ---

- ## 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?

---

## Boundaries

- Do not invent an activation event, retention correlation, cohort result, or benchmark when product data is unavailable.

- Do not change product flows, permissions, notifications, experiments, or analytics without explicit authorization.

- Do not add friction, forced invitations, premature paywalls, or manipulative progress mechanics merely to improve a local metric.

- Do not decide sensitive-data collection, consent, accessibility, or product-risk policy for the user.

## Routing

- Use `suede-signup` for registration before first-run onboarding.

- Use `suede-emails` for onboarding email sequences and `suede-paywalls` for upgrade moments.

- Use `suede-ab-testing` to validate onboarding changes and `suede-analytics` to measure activation.