/variable-rewards

name: variable-rewards
description: Generates a variable reward system with randomized rewards, daily bonuses, mystery box mechanics, and ethical engagement caps. Use when user wants daily spins, mystery boxes, random rewards, or gamification reward systems.
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

Variable Rewards Generator

Generate a variable reward system — randomized rewards (daily spins, mystery boxes, bonus points) that leverage variable-ratio reinforcement to increase engagement. Implements ethical engagement patterns with daily/weekly caps, transparent probability disclosure, and no pay-to-play mechanics.

When This Skill Activates

Use this skill when the user:

• Asks to "add daily rewards" or "daily spin" mechanic
• Wants a "reward system" or "random rewards"
• Mentions "mystery box" or "loot box" (non-paid)
• Asks about "bonus system" or "daily bonus"
• Wants "gamification rewards" or "engagement rewards"
• Mentions "reward wheel" or "spin to win"
• Asks about "variable rewards" or "intermittent reinforcement"

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)
• [ ] Check for SwiftData availability and existing model container setup
• [ ] Identify source file locations

2. Conflict Detection

Search for existing reward or points systems:

Glob: **/*Reward*.swift, **/*Points*.swift, **/*DailySpin*.swift, **/*MysteryBox*.swift
Grep: "reward" or "dailySpin" or "mysteryBox" or "rewardPool" or "lootBox"

If existing reward system found:

• Ask if user wants to replace or extend it
• If extending, generate only the missing components

3. Platform Detection

Determine if generating for iOS or macOS or both (cross-platform). The templates use SwiftUI and are cross-platform by default.

Configuration Questions

Ask user via AskUserQuestion:

1. **Reward types?** (multi-select)

• Points (numeric currency the user accumulates)
• Items (unlockable content: themes, stickers, avatars)
• Features (time-limited feature unlocks)
• Badges (collectible achievement badges)
• Mixed (all of the above) -- recommended

2. **Reward mechanism?**

• Daily spin (wheel animation, one spin per day)
• Mystery box (card-flip or chest-open, one per day)
• Random bonus (surprise toast notification on qualifying action)
• Multiple (daily spin + random bonus) -- recommended

3. **Include daily/weekly caps and cooldowns?**

• Yes — enforce max rewards per day and per week with cooldown timers (recommended, ethical design)
• No — unlimited claims (not recommended)

4. **Visual presentation?**

• Wheel spin (rotating wheel with segments)
• Card flip (card turns over to reveal reward)
• Chest open (chest lid opens with glow effect)
• All of the above -- recommended

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `Reward.swift` — Model for reward type, value, rarity, display metadata 2. `RewardPool.swift` — Weighted probability distribution with seeded random for testability 3. `RewardManager.swift` — @Observable class managing claims, daily resets, caps, history via SwiftData

Step 3: Create UI Files

4. `DailySpinView.swift` — Animated spin wheel with disabled state when already claimed 5. `MysteryBoxView.swift` — Card-flip / chest-open animation with matchedGeometryEffect 6. `RewardHistoryView.swift` — List of past rewards grouped by day 7. `RewardNotificationView.swift` — Toast/banner overlay for reward availability

Step 4: Determine File Location

Check project structure:

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

Output Format

After generation, provide:

Files Created

VariableRewards/
├── Reward.swift                  # Reward model with type, rarity, value
├── RewardPool.swift              # Weighted random selection engine
├── RewardManager.swift           # Core manager: claims, caps, history
├── DailySpinView.swift           # Animated spin wheel
├── MysteryBoxView.swift          # Card-flip / chest-open reveal
├── RewardHistoryView.swift       # Past rewards grouped by day
└── RewardNotificationView.swift  # Toast overlay for available rewards

Integration Steps

**Set up the model container (SwiftData):**

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

**Add the daily spin to your home screen:**

struct HomeView: View {
    @Environment(\.modelContext) private var modelContext
    @State private var rewardManager: RewardManager?

    var body: some View {
        VStack {
            if let manager = rewardManager {
                DailySpinView(manager: manager)
            }
        }
        .onAppear {
            rewardManager = RewardManager(modelContext: modelContext)
        }
    }
}

**Trigger a mystery box reveal:**

struct MilestoneView: View {
    @Environment(\.modelContext) private var modelContext
    @State private var rewardManager: RewardManager?
    @State private var showMysteryBox = false

    var body: some View {
        VStack {
            Button("Open Mystery Box") {
                showMysteryBox = true
            }
            .disabled(rewardManager?.canClaimToday == false)
        }
        .sheet(isPresented: $showMysteryBox) {
            if let manager = rewardManager {
                MysteryBoxView(manager: manager)
            }
        }
        .onAppear {
            rewardManager = RewardManager(modelContext: modelContext)
        }
    }
}

**Show a reward notification toast:**