/quick-win-session

name: quick-win-session
description: Generates guided first-action flows that help users achieve a meaningful result within 60 seconds to boost retention. Use when user wants quick win onboarding, time-to-value optimization, or first success moments.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Quick Win Session Generator

Generate a "quick win" session system that guides users to complete a meaningful action within their first 60 seconds. Reduces time-to-value by surfacing the simplest high-impact task, walking the user through it step by step, and celebrating completion. Critical for onboarding retention — users who achieve a quick win in the first minute are significantly more likely to return.

When This Skill Activates

Use this skill when the user:

• Asks about "quick win" flows or "first action" experiences
• Wants to reduce "time to value" or "time to first success"
• Mentions "guided first task" or "onboarding action"
• Asks about a "first success moment" or "activation metric"
• Wants to "get users to do something useful immediately"
• Mentions "new user activation" or "onboarding retention"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 17+ / macOS 14+ required for @Observable)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Identify source file locations

2. Existing Onboarding Detection

Search for existing onboarding code:

Glob: **/*Onboarding*.swift, **/*Welcome*.swift, **/*QuickWin*.swift, **/*FirstRun*.swift
Grep: "onboarding" or "firstLaunch" or "hasCompletedSetup" or "isNewUser"

If existing onboarding found:

• Ask if quick win should run after the existing onboarding or replace it
• If running after, integrate as the next step in the onboarding flow

3. User State Tracking Detection

Search for existing user defaults or state tracking:

Grep: "UserDefaults" or "@AppStorage" or "isFirstLaunch"

Determine how to persist quick win completion status (UserDefaults, AppStorage, SwiftData, etc.).

Configuration Questions

Ask user via AskUserQuestion:

1. **Quick win type?**

• Create first item (e.g., first note, first task, first photo)
• Complete profile (fill in name, avatar, preferences)
• Import data (bring in existing content from another source)
• Explore feature (guided tour of the single most valuable feature)

2. **Guidance style?**

• Step-by-step overlay (instruction cards at top, progress dots)
• Spotlight hints (dim screen, cut out spotlight on target element)
• Coach marks (tooltip arrows pointing at UI elements)

3. **Celebrate on completion?**

• Yes — animated checkmark, congratulations message, time stat
• Minimal — brief success banner, auto-dismiss
• No — silently mark as complete

4. **Track as activation metric?**

• Yes — log completion time, step-by-step progress, abandonment point
• No — just persist completed/not completed

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `QuickWinTask.swift` — Model for a quick win task and its steps 2. `QuickWinSession.swift` — @Observable session manager: task selection, step tracking, timing, completion

Step 3: Create UI Files

3. `QuickWinGuideView.swift` — Overlay that shows instructions and progress 4. `SpotlightHintView.swift` — Spotlight cutout overlay with callout arrow 5. `QuickWinCelebrationView.swift` — Completion celebration with stats

Step 4: Create Integration File

6. `QuickWinModifier.swift` — ViewModifier that triggers the quick win for new users

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists → `Sources/QuickWin/`
• If `App/` exists → `App/QuickWin/`
• Otherwise → `QuickWin/`

Output Format

After generation, provide:

Files Created

QuickWin/
├── QuickWinTask.swift           # Task model with steps
├── QuickWinSession.swift        # Session manager (progress, timing)
├── QuickWinGuideView.swift      # Step-by-step overlay UI
├── SpotlightHintView.swift      # Spotlight cutout with callout
├── QuickWinCelebrationView.swift # Completion celebration
└── QuickWinModifier.swift       # ViewModifier for root view

Integration After Onboarding

**Attach to your root view:**

// In your main ContentView or post-onboarding view
ContentView()
    .quickWinSession(task: .createFirstNote)

**Define your app's quick win task:**

extension QuickWinTask {
    static let createFirstNote = QuickWinTask(
        id: "create-first-note",
        title: "Create Your First Note",
        description: "Let's get started — it only takes a few seconds.",
        estimatedSeconds: 30,
        steps: [
            QuickWinStep(instruction: "Tap the + button to create a new note", actionType: .tap, targetView: "addButton"),
            QuickWinStep(instruction: "Type a title for your note", actionType: .input, targetView: "titleField"),
            QuickWinStep(instruction: "Tap Done to save", actionType: .tap, targetView: "doneButton")
        ],
        completionCriteria: "firstNoteCreated",
        iconName: "note.text.badge.plus"
    )
}

**With spotlight hints:**

// Mark target views for spotlight
TextField("Title", text: $title)
    .quickWinTarget(id: "titleField")

Button("Done") { save() }
    .quickWinTarget(id: "doneButton")

**Start session programmatically (after existing onboarding):**

struct PostOnboardingView: View {
    @State private var session = QuickWinSession()

    var body: some View {
        MainView()
            .onAppear {
                if !session.hasCompletedQuickWin {
                    session.start(task: .createFirstNote)
                }
            }
            .quickWinOverlay(session: session)
    }
}

Testing

@Test
func quickW