---
name: rating-prompt-strategy
description: Design when and to whom an app Product asks for a rating so the volume of 4–5 star ratings rises. Use for "rating prompt", "SKStoreReviewController", "ask for review", "get more ratings", "recover from a rating drop", "reset ratings for the new version". For answering existing reviews, use review-management.
metadata:
  version: 1.0.0
---

# Rating Prompt Strategy

Ratings are a ranking signal and the first thing a searcher compares. The lever is timing: prompting a user who just experienced value yields 4–5 stars, prompting a first-session user yields the 1-star that costs conversion for a version. Output is a **prompt strategy brief** with an **implementation checklist**; when the User asks, the checklist becomes a PR brief on the connected repo.

## Gather

1. `read_context` — activation event, core loop, success moments, current version and what it changed.
2. `app_store_listing` — current rating and rating count. The current velocity is today's count against the count a past report from `read_outputs` recorded; with none, say the velocity is unknown and write today's count into the brief for the next Run.
3. `connector_asc_analytics` when the ASC Connector exists — ratings per period, retention curve (when users are still around to be asked), conversion baseline. Without it, velocity is rating count at the last two snapshots, and say the ASC Connector would add the per-day trend.
4. `connector_asc_reviews` when available (fallback `app_store_reviews`) — which versions the 1–3 star reviews cluster on, and what they name.

## Design

Apply the rules in [`references/prompt-rules.md`](references/prompt-rules.md) — read it before designing: SKStoreReviewController limits, eligibility criteria, success moments per app type, pre-prompt survey, version reset, and the recovery timeline.

1. **Success moments** — one to three events from the Foundation doc where the user has just gained something. Each is named as an analytics event with its condition.
2. **Eligibility gate** — sessions, days since install, activation completed, clean last session, not yet asked this version.
3. **Pre-prompt survey** — one question ("Enjoying [Product]?"); "yes" calls the native prompt, "not really" opens the feedback form. Recommend it by default; skip only when the Foundation doc reports a rating ≥ 4.7 with healthy velocity.
4. **Frequency** — 1–2 calls per version, at most 3 per 365 days per device, one per session.
5. **Version reset** — recommend it only when the current version fixes the issues the low reviews name.
6. **Recovery plan** — when the rating is below 4.0 or dropped ≥ 0.3 in 30d: version diagnosed, fix, replies via `review-management`, then a filtered prompt campaign at the most engaged segment.

## Output: prompt strategy brief

```
Rating: X.X (N ratings) · velocity: N/week · trend vs previous version
Success moments: event → condition (1–3)
Pre-prompt survey: yes/no, wording
Eligibility gate: sessions ≥ N · days ≥ N · activation done · no crash last session · not asked this version
Frequency: N per version · one per session
Version reset: yes/no and why
Expected outcome: +X stars over N weeks
Recovery plan (when rating < 4.0): fix · replies · campaign start and segment
```

Then the **implementation checklist**: events to track, the gate as a boolean, the `requestReview(in:)` call site, the survey screen, the feedback form route, and the analytics to confirm it fires. On request, wrap it as a PR brief (files, acceptance criteria) for the connected repo.

Done when every success moment maps to a named event, the gate lists all six criteria with values, the frequency respects Apple's limit, and the brief names the velocity source (`connector_asc_analytics` or snapshots).

## Related Skills

- `review-management` — reply to the reviews a recovery depends on.
- `onboarding` — activation problems that produce first-session 1-stars.
- `churn-prevention` — engaged users are the ones worth asking.
- `subscription-lifecycle` — a converted subscriber at renewal is a strong moment.