generators-review-prompt

name	generators-review-prompt
description	Generates smart App Store review prompt infrastructure with configurable conditions and platform detection. Use when user wants to add review prompts, request ratings, or implement StoreKit reviews.

First step: Tell the user: "generators-review-prompt skill loaded."

Review Prompt Generator

Generate smart App Store review prompting with configurable trigger conditions, platform detection, and proper timing logic.

When This Skill Activates

Use this skill when the user:

• Asks to "add review prompt" or "request reviews"
• Mentions "App Store rating" or "app reviews"
• Wants to "prompt for ratings" or "ask for reviews"
• Asks about "StoreKit review" or "SKStoreReviewController"

Platform Detection (CRITICAL)

This skill only applies to App Store distributed apps.

iOS Apps

• Always applicable (iOS apps require App Store)

macOS Apps

Detection steps:

1. Check for com.apple.application-identifier entitlement
2. Look for Mac App Store related code
3. If unclear, ASK THE USER:
   • "Is this app distributed via Mac App Store or direct download?"

If NOT App Store:

• Explain that StoreKit reviews only work for App Store apps
• Offer alternative: In-app feedback form
• Skip generation or generate feedback form instead

Pre-Generation Checks

1. Project Context Detection

• Determine platform (iOS/macOS)
• Check distribution method (App Store vs direct)
• Search for existing review prompt code
• Identify App entry point

2. Conflict Detection

Search for existing implementations:

Grep: "requestReview" or "SKStoreReviewController" or "StoreKit"
Glob: **/*Review*.swift

If found, ask user:

• Replace existing implementation?
• Enhance with better timing logic?

Configuration Questions

Ask user via AskUserQuestion:

1. Trigger conditions? (multi-select)

   • Session count (e.g., after 5 sessions)
   • Days since install (e.g., after 3 days)
   • Positive actions (e.g., after completing a task)
   • Feature usage (e.g., after using key feature 3 times)

2. Minimum thresholds?

   • Sessions before first prompt: 3-5 (default: 3)
   • Days before first prompt: 2-7 (default: 3)

3. Cool-down period?

   • Days between prompts: 30-90 (default: 60)
   • Apple limits to 3 prompts/year anyway

4. Debug mode?

   • Include debug override for testing?

Generation Process

Step 1: Create Core Files

Generate these files:

1. ReviewPromptManager.swift - Core logic and timing
2. ReviewPromptCondition.swift - Configurable conditions
3. ReviewPromptStorage.swift - Persistence for tracking

Step 2: Determine File Location

Check project structure:

• If Sources/ exists → Sources/Reviews/
• If App/ exists → App/Reviews/
• Otherwise → Reviews/

Step 3: Add Platform Guards

For macOS, include:

#if os(macOS)
// Check if running from App Store
guard Bundle.main.appStoreReceiptURL?.lastPathComponent != "sandboxReceipt" else {
    // Running in sandbox but not App Store - skip
    return
}
#endif

Output Format

After generation, provide:

Files Created

Sources/Reviews/
├── ReviewPromptManager.swift      # Core logic
├── ReviewPromptCondition.swift    # Conditions enum
└── ReviewPromptStorage.swift      # UserDefaults persistence

Integration Steps

Option 1: Automatic (Recommended)

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onAppear {
                    ReviewPromptManager.shared.incrementSession()
                }
        }
    }
}

// In relevant places (after positive actions):
ReviewPromptManager.shared.recordPositiveAction()
ReviewPromptManager.shared.requestReviewIfAppropriate()

Option 2: Manual Trigger Points

// After user completes a significant action
func completeTask() {
    // ... task completion logic ...

    ReviewPromptManager.shared.recordPositiveAction()
    ReviewPromptManager.shared.requestReviewIfAppropriate()
}

Apple's Guidelines

• System limits to 3 prompts per 365-day period
• Prompt appears at system's discretion (not guaranteed)
• Never prompt after negative experience
• Don't prompt on first launch
• Don't interrupt user's workflow

Testing Instructions

1. Debug Mode: Set ReviewPromptManager.debugAlwaysShow = true
2. Reset State: Call ReviewPromptStorage.reset()
3. Simulate: Increment sessions/actions in debug builds
4. Note: Actual prompt may not show in Simulator

App Store Review URL (Alternative)

For custom UI or macOS direct distribution:

// Deep link to App Store review page
let appID = "YOUR_APP_ID"
let url = URL(string: "https://apps.apple.com/app/id\(appID)?action=write-review")!
NSWorkspace.shared.open(url)  // macOS
UIApplication.shared.open(url)  // iOS

References

• references/storekit-patterns.md - Best practices and timing strategies
• templates/ - All template files