/usage-insights

name: usage-insights
description: Generates user-facing usage statistics, activity summaries, and personalized insights dashboards (weekly recaps, year-in-review, Spotify Wrapped-style). Use when user wants to show usage stats, activity insights, or shareable recap screens. Different from analytics-setup which sends data to a backend — this shows insights to the USER on-device.
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

Usage Insights Generator

Generate a production usage insights system that records user activity events with SwiftData, computes personalized insights (streaks, most active day, top categories), and displays them in a dashboard with insight cards, period pickers, trend indicators, and optional shareable recap screens.

When This Skill Activates

Use this skill when the user:

• Asks to "show usage statistics" or "add usage stats"
• Wants "user insights" or "activity insights"
• Mentions "activity summary" or "weekly summary"
• Asks about a "usage dashboard" or "insights dashboard"
• Wants a "weekly recap" or "monthly recap"
• Mentions "year in review" or "year-in-review"
• Asks for "Spotify Wrapped style" or "Wrapped-style recap"
• Wants to "show the user their activity" or "personalized stats"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check deployment target (iOS 17+ / macOS 14+ for @Observable and SwiftData)
• [ ] Identify source file locations
• [ ] Check for Swift Charts availability (iOS 16+ / macOS 13+, but recommend iOS 17+)

2. Conflict Detection

Search for existing usage tracking or insights code:

Glob: **/*UsageEvent*.swift, **/*Insight*.swift, **/*Recap*.swift, **/*ActivityLog*.swift
Grep: "UsageEvent" or "InsightCalculator" or "activitySummary" or "SwiftData" and "event"

If existing analytics/tracking found:

• Ask if user wants to build insights on top of existing event data
• If yes, adapt `InsightCalculator` to work with existing models
• If no, generate fresh event recording alongside existing code

3. Data Layer Detection

Check for SwiftData usage:

Grep: "import SwiftData" or "@Model" or "ModelContainer"

If SwiftData already in use:

• Integrate `UsageEvent` into existing `ModelContainer`
• Use existing schema migration strategy

If no SwiftData:

• Generate full setup including `ModelContainer` configuration

Configuration Questions

Ask user via AskUserQuestion:

1. **Insight period?**

• Daily (today's activity breakdown)
• Weekly (7-day recap with day-by-day comparison) — recommended
• Monthly (30-day trends with weekly rollups)
• Yearly (year-in-review with monthly highlights)
• All of the above (period picker lets user switch)

2. **Visualization style?**

• Cards only (simple stat cards with trend indicators)
• Charts only (Swift Charts bar/line graphs)
• Both cards and charts — recommended

3. **Include shareable recap card?**

• Yes (generates a recap view that can be rendered to an image and shared)
• No (dashboard only, no sharing)

4. **Data source?**

• SwiftData (generate `UsageEvent` model and recorder) — recommended
• Custom (user provides their own event data; generate calculator and views only)

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Data Files

Generate these files: 1. `UsageEvent.swift` — SwiftData `@Model` for recording user activity events 2. `InsightResult.swift` — Model for computed insights (title, value, trend, visualization type)

Step 3: Create Calculation Engine

3. `InsightCalculator.swift` — Pure functions that aggregate events into insights

Step 4: Create UI Files

4. `InsightsDashboardView.swift` — Main dashboard with grid of insight cards and period picker 5. `InsightCardView.swift` — Individual insight card with icon, value, trend indicator, sparkline

Step 5: Create Optional Files

Based on configuration:

• `UsageRecapView.swift` — If shareable recap selected (paged summary with share card generation)
• `UsageEventRecorder.swift` — If SwiftData data source selected (convenience class for recording events)

Step 6: Determine File Location

Check project structure:

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

Output Format

After generation, provide:

Files Created

UsageInsights/
├── UsageEvent.swift           # SwiftData @Model for activity events
├── InsightResult.swift        # Computed insight model
├── InsightCalculator.swift    # Aggregation engine
├── InsightsDashboardView.swift # Dashboard with period picker
├── InsightCardView.swift      # Individual insight card
├── UsageRecapView.swift       # Shareable recap (optional)
└── UsageEventRecorder.swift   # Event recording helper (optional)

Integration Steps

**Add ModelContainer (if not already present):**

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: [UsageEvent.self])
    }
}

**Record events from anywhere in the app:**

struct TaskDetailView: View {
    @Environment(\.modelContext) private var modelContext
    @State private var recorder: UsageEventRecorder?

    var body: some View {
        Button("Complete Task") {
            completeTask()
            recorder?.record(
                .taskCompleted,
                metadata: ["category": "work", "priority": "high"]
            )
        }
        .onAppear {
            recorder = UsageEventRecorder(modelContext: modelContext)
        }
    }
}

**Show the insights dashboard:**

NavigationLink("My Insights") {
    InsightsDashboardView()
}

**Show a weekly recap:**

struct WeeklyRecapSheet: View {
    @Environment(\.modelContext) pri