Onboarding Generator

Onboarding Generator

Generate onboarding whose job is to get a new user to the value moment — the first time they experience (never just read about) the outcome the app promises — as fast as their situation allows.

Default architecture: value-moment-first, branching on readiness. The user answers one question ("can you do this right now?"), and the path is either the shortest possible route to the value moment, or a captured plan to reach it later. Fallback architecture: the classic paged welcome carousel — generate it only when Step 0 below confirms the app is genuinely explain-first.

Read onboarding-patterns.md for the full philosophy, the nine implementation lessons (each with a code sketch), and a worked case study.

When This Skill Activates

Use this skill when the user:

• Asks to "add onboarding" or "create onboarding"
• Mentions "welcome screens" or "first launch"
• Wants to "show intro on first launch"
• Asks about "onboarding flow" or "tutorial screens"
• Wants to improve "activation," "time-to-value," or "trial conversion"
• Asks "why do users churn right after signup/purchase" (post-purchase first-run is half of this skill)

Before Anything Else: What Is The Value Moment?

This is the question that decides every downstream choice — ask it before any configuration question. If the requester can't answer it, help them find it: it's the first specific instant a user feels the outcome, not a feature list. "Sees a demo of X" is not a value moment; "actually did X and saw the result" is.

Onboarding that ends before the user felt the value moment didn't finish — it just stopped.

Pre-Generation Checks

1. Project Context Detection

• Check deployment target (@Observable needs iOS 17+/macOS 14+; fall back to ObservableObject below that)
• Identify the app's core feature and its existing entry point — the value moment almost always lives inside a feature that already exists (or is being built alongside this flow); this skill wires into it, it does not rebuild it (see onboarding-patterns.md Lesson 3)
• Check whether the app has a launch paywall (Glob: **/*Paywall*.swift, **/*StoreKit*.swift, or an installed generators/paywall-generator output) — determines free-first vs paywalled-first in Configuration Question 2
• Check for UNUserNotificationCenter usage already in the project — reuse the existing permission seam if one exists rather than creating a second

2. Conflict Detection

Glob: **/*Onboarding*.swift, **/*Welcome*.swift
Grep: "hasCompletedOnboarding" or "isFirstLaunch" or "onboardingCompleted"

If found, ask the user:

• Replace existing onboarding?
• Keep existing, add the value-moment flow as a new post-purchase/post-launch stage?

3. Overlap Check — generators/quick-win-session

If the project already has a quick-win-session installation, don't generate a second guided-first-action system. Ask whether the existing quick-win session already is the ready-now path (often it is — fold this flow's branch question and later-path in around it) or whether the two should stay separate stages.

Configuration Questions

Ask user via AskUserQuestion:

1. What's the value moment? (free text) — the first specific instant the user experiences the app's promise. Push back on feature descriptions ("a calendar sync feature") until you get an outcome ("saw their two calendars merged into one").

2. Free-first or paywalled-first?

   • Free-first (no launch paywall) — this flow is the whole onboarding
   • Paywalled-first — personalize → paywall happens before this flow starts; this flow begins at first-run-after-purchase (the half that decides trial conversion and renewals)

3. What's the ready-now action? — the shortest real path to the value moment when the user can experience it immediately. Must name an existing feature/screen to reuse, never a new one built just for onboarding.

4. What does "later" capture? — the concrete implementation intention (a specific when, e.g. "Tuesday 6pm," never "someday"), and what happens with it: a local reminder, a home-surface chip, both?

5. Architecture override — is this genuinely explain-first? Default is no (value-moment-first). Only say yes if Step 0's test below is met. This is the one question that routes to the carousel fallback instead.

Generation Process

Step 0: Confirm The Architecture (do this before writing any file)

Run this test:

Would skipping straight to the value moment leave the user unable to understand what they're looking at, in a way no amount of contextual UI (tooltips, empty-state copy, a single explainer inline) could fix — because the domain itself requires orientation (e.g., a professional tool with domain-specific jargon, a multi-role enterprise workflow)?

• No (the overwhelming default) → generate the value-moment-first flow (Steps 1–5).
• Yes → generate the carousel fallback (Step 6). "We have a lot to say" is not a yes — trim the copy instead.

Step 1: Create Core Files (Value-Moment Default)

Read templates/value-moment/ for production Swift code, then generate:

1. OnboardingPhase.swift — the phase/branch state model (one enum case per screen; every case maps to exactly one decision)
2. OnboardingStore.swift — @Observable coordinator (plain object, not a View — see onboarding-patterns.md Lesson 1's testability point). Owns phase transitions, the branch, the captured "when," and calls into instrumentation. No navigation/routing types inside it — the app's existing router/state owns side effects, this store owns only business state.
3. OnboardingRootView.swift — the phase switch. No NavigationStack of its own (this view is a root, never a pushed destination — see the global SwiftUI-patterns rule against nesting nav containers).
4. OnboardingBranchView.swift — screen 1: value-moment framing + the ready-now/later fork. This is the only screen every user sees.
5. OnboardingReadyNowBridgeView.swift — the ready-now hand-off into the real feature, with resume-callback wiring (Lesson 3 + Lesson 4)
6. OnboardingIntentionView.swift — later path: capture the concrete "when" via chips, resolved through a pure, injectable-clock function (Lesson 7)
7. OnboardingReminderView.swift + OnboardingReminderService.swift — later path: the contextual local-notification permission ask (Lesson 6)
8. OnboardingInstrumentation.swift — value-moment reach-rate markers (Lesson 8)

Step 2: Wire The Root Swap (Lesson 1 — required)

Onboarding replaces the app's root view; it is never a .fullScreenCover/.sheet over the real content. Show the requester this shape and adapt it to their app's actual root:

struct ContentView: View {
    @State private var onboardingStore = OnboardingStore()

    private var showOnboarding: Bool {
        // Phase-first (Lesson 2): check the in-memory state machine FIRST;
        // the durable flag is only the survives-relaunch fallback.
        if appState.onboardingCompleted { return false }
        return onboardingStore.phase != .completed && onboardingStore.phase != .awaitingHandoffReturn
    }

    var body: some View {
        Group {
            if showOnboarding {
                OnboardingRootView(store: onboardingStore)
            } else {
                RealAppRootView()   // whatever the app's true root already is
            }
        }
        .onChange(of: onboardingStore.phase) { _, newPhase in
            guard newPhase == .completed else { return }
            appState.onboardingCompleted = true   // durable fallback catches up
        }
    }
}

Step 3: Wire Resume Mechanics (Lesson 4 — required whenever the ready-now action hands off into an existing multi-screen flow)

Arm a one-shot completion callback before the hand-off, plus a wander-off safety net that completes onboarding silently if the user backs out without resolving:

func beginReadyNowHandoff() {
    store.beginHandoff()
    router.presetPathIntoRealFeature(...)          // land straight on the feature, never Home
    router.onRealFeatureFinished = { outcome in
        store.handoffReturned(valueMomentReached: outcome.reachedValueMoment)
    }
}

// Safety net — user backed all the way out without the callback firing.
.onChange(of: router.path) { _, newPath in
    guard store.phase == .awaitingHandoffReturn, newPath.isEmpty else { return }
    store.abandonToHome()   // NEVER re-interrupts; completes quietly
}

Step 4: Suppress Onboarding In Existing UI Tests (Lesson 5 — required step, not optional)

Adding this flow will break the first screen of every existing UI test that assumes it lands on the app's real home screen. Before finishing generation:

1. Find the project's UI-test launch-argument gate (ProcessInfo.processInfo.arguments), usually in a UITestSupport-style file.
2. Add an onboarding-suppression default: existing test launches pre-set the durable completed flag unless a new, dedicated argument opts back in.

static var showOnboardingOverride: Bool {
    ProcessInfo.processInfo.arguments.contains("-uiTestShowOnboarding")
}
// At app launch, under the existing test-mode gate:
appState.onboardingCompleted = !UITestSupport.showOnboardingOverride

3. Tell the requester explicitly which existing test target this touches and that a dedicated onboarding UI test should pass -uiTestShowOnboarding to exercise the real flow.