name: check-onboarding
description: |
Audit onboarding: first-run, time to aha, friction points, empty states.
Outputs structured findings. Use log-onboarding-issues to create issues.
Invoke for: onboarding review, new user experience, activation audit.

/check-onboarding

Audit user onboarding experience. Output findings as structured report.

What This Does

1. Check first-run experience
2. Measure time to "aha moment"
3. Identify friction points
4. Check empty states
5. Check progressive disclosure
6. Output prioritized findings (P0-P3)

This is a primitive. It only investigates and reports. Use /log-onboarding-issues to create GitHub issues or /fix-onboarding to fix.

Process

1. First-Run Experience Check

# Onboarding flow exists?
find . -path "*onboarding*" -name "*.tsx" 2>/dev/null | head -5
find . -path "*welcome*" -name "*.tsx" 2>/dev/null | head -5

# New user detection?
grep -rE "isNewUser|firstVisit|hasCompletedOnboarding|onboardingComplete" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Tour/walkthrough?
grep -rE "tour|Tour|walkthrough|Walkthrough|shepherd|driver\.js|intro\.js" --include="*.tsx" --include="*.ts" . 2>/dev/null | grep -v node_modules | head -5

2. Authentication Flow Check

# Auth callback handling?
find . -path "*callback*" -o -path "*auth*" -name "*.tsx" 2>/dev/null | head -5

# Post-signup redirect?
grep -rE "signUp.*redirect|afterSignUp|signUpUrl" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Profile completion?
grep -rE "completeProfile|setupProfile|profile.*setup" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

3. Empty States Check

# Empty state components?
grep -rE "empty|Empty|no.*found|NoResults|EmptyState" --include="*.tsx" components/ 2>/dev/null | head -5

# Placeholder content for new users?
grep -rE "placeholder|getStarted|Get Started|Create.*first" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Loading states?
grep -rE "loading|Loading|skeleton|Skeleton|shimmer" --include="*.tsx" components/ 2>/dev/null | head -5

4. Friction Point Detection

# Required fields on first interaction?
grep -rE "required|isRequired|\*.*required" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -10

# Form complexity?
form_fields=$(grep -rE "<input|<Input|<TextField" --include="*.tsx" . 2>/dev/null | grep -v node_modules | wc -l | tr -d ' ')
echo "Form fields count: $form_fields"

# Payment wall before value?
grep -rE "subscribe.*before|payment.*required|upgrade.*to" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

5. Progressive Disclosure Check

# Tooltips for guidance?
grep -rE "tooltip|Tooltip|hint|Hint" --include="*.tsx" components/ 2>/dev/null | head -5

# Feature discovery?
grep -rE "new.*feature|beta|coming.*soon|tip|Tip" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Contextual help?
grep -rE "help|Help|info|Info|learn.*more|LearnMore" --include="*.tsx" components/ 2>/dev/null | head -5

6. Aha Moment Path

Analyze the path to core value:

# Main action identification
grep -rE "create|Create|add|Add|import|Import|generate|Generate" --include="*.tsx" app/ 2>/dev/null | head -10

# Steps to first success?
# Check for multi-step forms, wizards, or complex setup
grep -rE "step|Step|wizard|Wizard|progress|Progress" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

7. Retention Hooks

# Notification permissions?
grep -rE "Notification|push|Push|notification" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Email capture?
grep -rE "email|newsletter|subscribe" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

# Save progress?
grep -rE "draft|Draft|autosave|Autosave|save.*progress" --include="*.tsx" . 2>/dev/null | grep -v node_modules | head -5

Output Format

## Onboarding Audit

### P0: Critical (Users Immediately Lost)
- No onboarding flow - Users dropped into empty app
- Auth callback broken - Users stuck after signup
- Required payment before seeing product value

### P1: Essential (Activation Blockers)
- No empty states - Blank screens confuse new users
- No guidance on first action
- Complex form on first interaction (15+ fields)
- No loading states (user thinks app is broken)

### P2: Important (Friction Reducers)
- No progressive disclosure (all features visible immediately)
- No tooltips/hints for new users
- No tour/walkthrough option
- Post-signup redirect goes to generic dashboard

### P3: Retention Enhancers
- No notification permission request
- No email capture for non-logged-in users
- No "save progress" for long workflows
- No "welcome back" experience

## Onboarding Metrics (Estimated)
- Steps to first value: 5+ (target: 2-3)
- Required fields before value: 8 (target: 0-2)
- Time to "aha": Unknown (add analytics)

## Current Status
- First-run flow: Missing
- Empty states: Partial
- Progressive disclosure: None
- Friction level: High

## Summary
- P0: 1 | P1: 4 | P2: 4 | P3: 3
- Recommendation: Add empty states and reduce first-action friction

Priority Mapping

Related

• /log-onboarding-issues - Create GitHub issues from findings
• /fix-onboarding - Fix onboarding issues
• /cro - Conversion rate optimization