/whats-new

name: whats-new
description: Generates a "What's New" / changelog screen shown after app updates with version tracking, feature highlights, and one-time display per version. Use when user wants release notes UI, update notifications, or feature announcements.
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

What's New Generator

Generate a complete "What's New" screen that displays after app updates — highlights new features, changes, and improvements with version tracking to ensure it only shows once per update.

When This Skill Activates

Use this skill when the user:

• Asks to "add a what's new screen" or "show what's new"
• Mentions "changelog" or "changelog UI"
• Wants an "app update screen" or "update notification"
• Asks about "new features screen" or "feature announcements"
• Mentions "release notes UI" or "release notes screen"
• Wants a "version update notification" or "post-update screen"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 16+ / macOS 13+ minimum; iOS 17+ / macOS 14+ for @Observable)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Identify source file locations and project structure
• [ ] Determine how app version is accessed (`Bundle.main.infoDictionary`, custom build config, etc.)

2. Conflict Detection

Search for existing what's new or changelog implementations:

Glob: **/*WhatsNew*.swift, **/*Changelog*.swift, **/*ReleaseNotes*.swift, **/*VersionTracker*.swift
Grep: "WhatsNew" or "whatsNew" or "lastShownVersion" or "changelog"

If found, ask user:

• Replace existing implementation?
• Keep existing, integrate alongside?

3. Version Access Pattern

Detect how the app reads its version:

Grep: "CFBundleShortVersionString" or "Bundle.main.infoDictionary" or "appVersion"

Use whichever pattern the project already employs. If none found, default to `Bundle.main.infoDictionary?["CFBundleShortVersionString"]`.

Configuration Questions

Ask user via AskUserQuestion:

1. **Presentation style?**

• Sheet (recommended — `.sheet(item:)` auto-dismiss)
• Full-screen cover (`.fullScreenCover`)
• Inline (embedded in a view hierarchy)

2. **Content source?**

• Hardcoded in Swift (simplest, no network needed)
• Local JSON file bundled in app
• Remote JSON endpoint (fetched on launch)

3. **Dismiss behavior?**

• "Continue" button (explicit acknowledgment)
• Swipe to dismiss (sheet default)
• Both (button + swipe)

4. **Page indicators?**

• Dot indicators (TabView page style)
• Page count label ("1 of 3")
• None (single scrollable view)

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `WhatsNewFeature.swift` — Model for a single feature (title, description, SF Symbol, tint color) 2. `WhatsNewRelease.swift` — Groups features by version string with date 3. `VersionTracker.swift` — Tracks last-shown version in UserDefaults, compares against current bundle version 4. `WhatsNewProvider.swift` — Protocol + local implementation (optional remote)

Step 3: Create UI Files

5. `WhatsNewView.swift` — Paged view with TabView(.page) showing features 6. `WhatsNewSheet.swift` — Wrapper that auto-presents via `.sheet(item:)` when new version detected

Step 4: Create Optional Files

Based on configuration:

• `RemoteWhatsNewProvider.swift` — If remote content source selected
• `WhatsNewJSON.swift` — If local JSON source selected

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/WhatsNew/`
• If `App/` exists -> `App/WhatsNew/`
• Otherwise -> `WhatsNew/`

Output Format

After generation, provide:

Files Created

WhatsNew/
├── WhatsNewFeature.swift       # Single feature model
├── WhatsNewRelease.swift       # Version-grouped features
├── VersionTracker.swift        # Version persistence & comparison
├── WhatsNewProvider.swift      # Content provider protocol + local impl
├── WhatsNewView.swift          # Paged feature display
├── WhatsNewSheet.swift         # Auto-presenting sheet wrapper
└── RemoteWhatsNewProvider.swift # Remote content (optional)

Integration Steps

**Option 1: View Modifier Style (Recommended)**

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .whatsNewSheet()  // Automatically shows after updates
        }
    }
}

**Option 2: Manual Control in Root View**

@main
struct MyApp: App {
    @State private var whatsNewRelease: WhatsNewRelease?

    var body: some Scene {
        WindowGroup {
            ContentView()
                .sheet(item: $whatsNewRelease) { release in
                    WhatsNewView(release: release)
                }
                .task {
                    let tracker = VersionTracker()
                    if tracker.shouldShowWhatsNew() {
                        whatsNewRelease = WhatsNewProvider.local.latestRelease()
                    }
                }
        }
    }
}

**Option 3: Inline Embedding**

struct HomeView: View {
    @State private var tracker = VersionTracker()

    var body: some View {
        VStack {
            if tracker.shouldShowWhatsNew(),
               let release = WhatsNewProvider.local.latestRelease() {
                WhatsNewView(release: release) {
                    tracker.markVersionAsShown()
                }
            }
            // Rest of home content...
        }
    }
}

Adding New Releases

// In LocalWhatsNewProvider.swift — add a new entry per release
static let releases: [WhatsNewRelease] = [
    WhatsNewRelease(
        version: "2.1.0",
        date: Date(timeIntervalSince1970: 1_700_000_000),
        features: [
            WhatsNewFeature(
                title: "Dark Mode Support",