Ratings Mechanics

---
name: ratings-mechanics
description: How App Store ratings actually behave — per-storefront isolation (your US stars show nowhere else), the never-reset rule, phased release + manual release as rating protection, and where prompting/replying fit. Use when planning ratings strategy for new markets, considering a ratings reset, setting release options, or diagnosing "why is my rating missing in country X."
allowed-tools: [Read, Write, Edit, Glob, Grep]
last_verified: 2026-07-16
review_by: 2027-06-22
---

# Ratings Mechanics

The rating is an asset with mechanics most developers learn the hard way. This skill covers the
four rules that aren't obvious from the ASC UI. Prompting *code* lives in
`generators/review-prompt`; reply *writing* lives in `app-store/review-response-writer` — this
skill is the strategy layer that tells you when each matters.

## When This Skill Activates

- Localizing or expanding into new storefronts ("why does my app show no rating in Japan?")
- Considering the "reset ratings summary" option on a version release
- Choosing release options before submitting (phased vs immediate, auto vs manual)
- Planning a per-market ratings strategy alongside `product/localization-strategy`
- A bad build or review-bomb is threatening the rating

## Rule 1: Ratings are per-storefront — they do not travel

Your 4.8★ from 2,000 US ratings renders as **no rating at all** on the Japanese storefront until
Japanese users rate the app there. Every storefront starts from zero.

Consequences:

- ✅ Entering a new market = re-running the early-days ratings playbook *in that market*: prompt
  eagerly (within guidelines), localize the prompt moment, reply to every early review.
- ✅ Weight `requestReview` triggers by storefront maturity — a market with 12 ratings needs the
  prompt more than the home market with 5,000.
- ❌ Assuming social proof transfers with the binary. A localized listing with zero local ratings
  converts like an unknown app, because there it *is* one.
- The written-review pool is also per-storefront: expect empty review sections in fresh markets
  and seed them via TestFlight communities or launch outreach in that region.

## Rule 2: Never reset the ratings summary

ASC offers a reset when you release a new version. It is almost always a mistake:

- Reset discards the count as well as the average — 4.2★ from 3,000 ratings converts better than
  a naked 5.0★ from 6, and the count never comes back except one rating at a time.
- The instinct to reset ("v2 is a big rewrite, old reviews don't apply") is better served by
  replying to outdated negative reviews (updated ratings **replace** the old score — see
  `review-response-writer`) and by the What's New copy.
- ✅ Legitimate near-exception: a catastrophic launch (sub-3★, low count, fixed root cause) on an
  app with almost no ratings mass. Even then, run the math on count loss first.
- ❌ Resetting an established app to chase a higher average. You'll rank and convert worse for
  months.

## Rule 3: Phased release + manual release are rating armor

Two ASC toggles turn a bad build from a rating catastrophe into a contained incident:

- **Manual version release** — approval ≠ release. Release when you're awake and watching
  crash dashboards, not whenever review finishes.
- **Phased release** — 7-day staged rollout (1% → 2% → 5% → 10% → 20% → 50% → 100%) to users
  with automatic updates. A crashing build caught on day 1–2 has burned ~3% of your users;
  **pause** the rollout, fix, resubmit. Without it, 100% of users get the bad build and the
  1-star flood arrives before the hotfix does.
- ✅ Default for every release: phased ON + manual release + monitor day-1 crash rate.
- ❌ Halting a phased release as a rollback. Pausing stops *new* deliveries only — users who got
  the build keep it, and manual App Store downloads always get the new version. The armor is
  damage *limitation*; the fix still has to ship.

## Rule 4: The prompt-and-reply loop is the only rating input you control

- **Prompt** at success moments with `requestReview` — never at launch, never mid-task. Aim the
  moment, cap the frequency, and localize what "success" means per market. Implementation:
  `generators/review-prompt`.
- **Reply** to negative reviews — when a user updates their review after a reply, the new score
  replaces the old one in the average. Replies are the only mechanism that converts existing
  1-stars into 4-stars. Templates: `app-store/review-response-writer`.
- Per-storefront corollary: track "unanswered negative reviews" per market, not globally — a
  5-review storefront is one bad review away from 60% negative.

## Output Format

When auditing an app's ratings posture, report per storefront:

```
Storefront | Rating (count) | Unanswered 1–3★ (90d) | Prompt localized? | Phased+manual habit?
```

flagging: fresh storefronts with no prompting plan, any reset consideration (🔴 stop), and
releases going out unphased.

## References

- https://developer.apple.com/documentation/storekit/requesting-app-store-reviews
- https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases
- https://developer.apple.com/help/app-store-connect/monitor-app-performance/reset-your-app-s-summary-rating
- Related skills: `generators/review-prompt`, `app-store/review-response-writer`, `product/localization-strategy`, `growth/store-growth-audit`