ratings-mechanics

Name: ratings-mechanics
Author: rshankras

548stars46forks

How to install ratings-mechanics?

rshankras/claude-code-apple-skills/ratings-mechanics

$npx -y skills add rshankras/claude-code-apple-skills --skill ratings-mechanics

Installs into the current project.

Summary

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 rati

Files · 1

View on GitHub

SKILL.md

1	# Ratings Mechanics
2
3	The rating is an asset with mechanics most developers learn the hard way. This skill covers the
4	four rules that aren't obvious from the ASC UI. Prompting code lives in
5	`generators/review-prompt`; reply writing lives in `app-store/review-response-writer` — this
6	skill is the strategy layer that tells you when each matters.
7
8	## When This Skill Activates
9
10	- Localizing or expanding into new storefronts ("why does my app show no rating in Japan?")
11	- Considering the "reset ratings summary" option on a version release
12	- Choosing release options before submitting (phased vs immediate, auto vs manual)
13	- Planning a per-market ratings strategy alongside `product/localization-strategy`
14	- A bad build or review-bomb is threatening the rating
15
16	## Rule 1: Ratings are per-storefront — they do not travel
17
18	Your 4.8★ from 2,000 US ratings renders as no rating at all on the Japanese storefront until
19	Japanese users rate the app there. Every storefront starts from zero.
20
21	Consequences:
22
23	- ✅ Entering a new market = re-running the early-days ratings playbook in that market: prompt
24	eagerly (within guidelines), localize the prompt moment, reply to every early review.
25	- ✅ Weight `requestReview` triggers by storefront maturity — a market with 12 ratings needs the
26	prompt more than the home market with 5,000.
27	- ❌ Assuming social proof transfers with the binary. A localized listing with zero local ratings
28	converts like an unknown app, because there it is one.
29	- The written-review pool is also per-storefront: expect empty review sections in fresh markets
30	and seed them via TestFlight communities or launch outreach in that region.
31
32	## Rule 2: Never reset the ratings summary
33
34	ASC offers a reset when you release a new version. It is almost always a mistake:
35
36	- Reset discards the count as well as the average — 4.2★ from 3,000 ratings converts better than
37	a naked 5.0★ from 6, and the count never comes back except one rating at a time.
38	- The instinct to reset ("v2 is a big rewrite, old reviews don't apply") is better served by
39	replying to outdated negative reviews (updated ratings replace the old score — see
40	`review-response-writer`) and by the What's New copy.
41	- ✅ Legitimate near-exception: a catastrophic launch (sub-3★, low count, fixed root cause) on an
42	app with almost no ratings mass. Even then, run the math on count loss first.
43	- ❌ Resetting an established app to chase a higher average. You'll rank and convert worse for
44	months.
45
46	## Rule 3: Phased release + manual release are rating armor
47
48	Two ASC toggles turn a bad build from a rating catastrophe into a contained incident:
49
50	- Manual version release — approval ≠ release. Release when you're awake and watching
51	crash dashboards, not whenever review finishes.
52	- Phased release — 7-day staged rollout (1% → 2% → 5% → 10% → 20% → 50% → 100%) to users
53	with automatic updates. A crashing build caught on day 1–2 has burned ~3% of your users;
54	pause the rollout, fix, resubmit. Without it, 100% of users get the bad build and the
55	1-star flood arrives before the hotfix does.
56	- ✅ Default for every release: phased ON + manual release + monitor day-1 crash rate.
57	- ❌ Halting a phased release as a rollback. Pausing stops new deliveries only — users who got
58	the build keep it, and manual App Store downloads always get the new version. The armor is
59	damage limitation; the fix still has to ship.
60
61	## Rule 4: The prompt-and-reply loop is the only rating input you control
62
63	- Prompt at success moments with `requestReview` — never at launch, never mid-task. Aim the
64	moment, cap the frequency, and localize what "success" means per market. Implementation:
65	`generators/review-prompt`.
66	- Reply to negative reviews — when a user updates their review after a reply, the new score
67	replaces the old one in the average. Replies are the only mechanism that converts existing
68	1-stars into 4-stars. Templates: `app-store/review-response-writer`.
69	- Per-storefront corollary: track "unanswered negative reviews" per market, not globally — a
70	5-review storefront is one bad review away from 60% negative.
71
72	## Output Format
73
74	When auditing an app's ratings posture, report per storefront:
75
76	```
77	Storefront \| Rating (count) \| Unanswered 1–3★ (90d) \| Prompt localized? \| Phased+manual habit?
78	```
79
80	flagging: fresh storefronts with no prompting plan, any reset consideration (🔴 stop), and
81	releases going out unphased.
82
83	## References
84
85	- https://developer.apple.co

People who liked this also viewed

6 picks

Type

ratings-mechanics

548stars46forks

View on GitHub

How to install ratings-mechanics?

rshankras/claude-code-apple-skills/ratings-mechanics

$npx -y skills add rshankras/claude-code-apple-skills --skill ratings-mechanics

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Ratings Mechanics
2
3	The rating is an asset with mechanics most developers learn the hard way. This skill covers the
4	four rules that aren't obvious from the ASC UI. Prompting code lives in
5	`generators/review-prompt`; reply writing lives in `app-store/review-response-writer` — this
6	skill is the strategy layer that tells you when each matters.
7
8	## When This Skill Activates
9
10	- Localizing or expanding into new storefronts ("why does my app show no rating in Japan?")
11	- Considering the "reset ratings summary" option on a version release
12	- Choosing release options before submitting (phased vs immediate, auto vs manual)
13	- Planning a per-market ratings strategy alongside `product/localization-strategy`
14	- A bad build or review-bomb is threatening the rating
15
16	## Rule 1: Ratings are per-storefront — they do not travel
17
18	Your 4.8★ from 2,000 US ratings renders as no rating at all on the Japanese storefront until
19	Japanese users rate the app there. Every storefront starts from zero.
20
21	Consequences:
22
23	- ✅ Entering a new market = re-running the early-days ratings playbook in that market: prompt
24	eagerly (within guidelines), localize the prompt moment, reply to every early review.
25	- ✅ Weight `requestReview` triggers by storefront maturity — a market with 12 ratings needs the
26	prompt more than the home market with 5,000.
27	- ❌ Assuming social proof transfers with the binary. A localized listing with zero local ratings
28	converts like an unknown app, because there it is one.
29	- The written-review pool is also per-storefront: expect empty review sections in fresh markets
30	and seed them via TestFlight communities or launch outreach in that region.
31
32	## Rule 2: Never reset the ratings summary
33
34	ASC offers a reset when you release a new version. It is almost always a mistake:
35
36	- Reset discards the count as well as the average — 4.2★ from 3,000 ratings converts better than
37	a naked 5.0★ from 6, and the count never comes back except one rating at a time.
38	- The instinct to reset ("v2 is a big rewrite, old reviews don't apply") is better served by
39	replying to outdated negative reviews (updated ratings replace the old score — see
40	`review-response-writer`) and by the What's New copy.
41	- ✅ Legitimate near-exception: a catastrophic launch (sub-3★, low count, fixed root cause) on an
42	app with almost no ratings mass. Even then, run the math on count loss first.
43	- ❌ Resetting an established app to chase a higher average. You'll rank and convert worse for
44	months.
45
46	## Rule 3: Phased release + manual release are rating armor
47
48	Two ASC toggles turn a bad build from a rating catastrophe into a contained incident:
49
50	- Manual version release — approval ≠ release. Release when you're awake and watching
51	crash dashboards, not whenever review finishes.
52	- Phased release — 7-day staged rollout (1% → 2% → 5% → 10% → 20% → 50% → 100%) to users
53	with automatic updates. A crashing build caught on day 1–2 has burned ~3% of your users;
54	pause the rollout, fix, resubmit. Without it, 100% of users get the bad build and the
55	1-star flood arrives before the hotfix does.
56	- ✅ Default for every release: phased ON + manual release + monitor day-1 crash rate.
57	- ❌ Halting a phased release as a rollback. Pausing stops new deliveries only — users who got
58	the build keep it, and manual App Store downloads always get the new version. The armor is
59	damage limitation; the fix still has to ship.
60
61	## Rule 4: The prompt-and-reply loop is the only rating input you control
62
63	- Prompt at success moments with `requestReview` — never at launch, never mid-task. Aim the
64	moment, cap the frequency, and localize what "success" means per market. Implementation:
65	`generators/review-prompt`.
66	- Reply to negative reviews — when a user updates their review after a reply, the new score
67	replaces the old one in the average. Replies are the only mechanism that converts existing
68	1-stars into 4-stars. Templates: `app-store/review-response-writer`.
69	- Per-storefront corollary: track "unanswered negative reviews" per market, not globally — a
70	5-review storefront is one bad review away from 60% negative.
71
72	## Output Format
73
74	When auditing an app's ratings posture, report per storefront:
75
76	```
77	Storefront \| Rating (count) \| Unanswered 1–3★ (90d) \| Prompt localized? \| Phased+manual habit?
78	```
79
80	flagging: fresh storefronts with no prompting plan, any reset consideration (🔴 stop), and
81	releases going out unphased.
82
83	## References
84
85	- https://developer.apple.co

People who liked this also viewed

6 picks

Type