references/release_notes_guidelines.md
# Release Notes Guidelines
Rules and examples for writing engaging App Store release notes (What's New).
## Structure
Three optional sections. Only include sections with content — omit empty ones.
- **New** — new features or capabilities
- **Improved** — enhancements to existing features
- **Fixed** — bug fixes users would notice
## The 170-Character Rule
The first ~170 characters of What's New are visible on the app page without tapping "more." This is the hook.
- Lead with the single most impactful change
- Write a complete, compelling sentence — not a truncated list
- Assume most users will never tap "more"
Example hook (168 chars):
"Search just got faster — find what you need in seconds. Plus: smarter notifications and smoother transitions throughout the app."
## Tone
- **Benefit-focused, not feature-focused.** "Find your favorites in seconds" not "Optimized search indexing algorithm."
- **Engaging but not fluffy** — every word earns its place
- **Direct address ("you")** to create connection
- **Action verbs** over passive descriptions ("Track your progress" not "Progress tracking added")
- **Specific over vague** — mention concrete improvements, not abstract promises
## Anti-Patterns
| Don't | Why |
|-------|-----|
| "Bug fixes and improvements" | Tells the user nothing. Wastes the conversion opportunity. |
| "Version 2.1.0 — We've been working hard!" | Version numbers in headings violate Apple guidelines. Self-congratulation wastes space. |
| Mentioning competitors by name | Against App Store Review Guidelines. |
| References to other platforms | "Now matching our Android version" alienates iOS users. |
| Keyword stuffing | What's New is NOT indexed for search. Every word should serve conversion, not SEO. |
| Marketing fluff with no substance | "The best update ever!" without specifics erodes trust. |
| Walls of text | Users skim. Use short paragraphs or bullet points. |
## Good vs. Bad Examples
**Bad:**
"Bug fixes and performance improvements."
**Good:**
"Search just got faster — find what you need in seconds. Plus: improved notification accuracy and smoother transitions throughout the app."
---
**Bad:**
"Version 2.1.0 — We've been working hard on improvements!"
**Good:**
"New sleep timer options let you drift off to soothing audio. Choose 15, 30, 45, or 60 minutes — perfect for winding down before bed."
---
**Bad:**
"Fixed bugs. Updated UI. Various improvements across the app."
**Good:**
"Real-time highlighting is now perfectly synced, even at 2x speed. Dark mode colors are easier on the eyes, and the app launches 40% faster."
---
**Bad:**
"We fixed a crash that some users reported. Also updated some things in the background."
**Good:**
"No more crashes when switching between tabs — thanks for reporting this! Background sync is now 3x faster, so your data stays up to date."
## Keyword Echo Strategy
What's New is **not indexed** for App Store search. Keywords here serve **conversion only** — users who see familiar search terms in the release notes feel confident they found the right app.
**How to echo:**
1. Read the locale's `keywords` field from local metadata
2. Identify keywords relevant to the changes being described
3. Weave them naturally into sentences — do NOT force irrelevant keywords
4. If the keywords field is empty or missing, skip this step
**Example:** If keywords include `workout,tracker,calories`:
"Improved workout tracking accuracy and real-time calorie counter updates" naturally echoes three keywords.
**Do NOT:** Insert keywords that have nothing to do with the update. "Bug fix for login screen" should not mention "workout" or "calories."
## Promotional Text Pairing
When drafting What's New, optionally draft a matching **Promotional Text** (170 chars max):
- Summarize the update's theme in one punchy line
- Can reference seasonal events (Ramadan, Eid, back-to-school, New Year)
- **Updatable without app submission** — the only "living" metadata field
- Not indexed for search — write purely for conversion
- Refresh monthly or with each major update for re-engagement
**Example:** "New sleep timer + faster search. Your evening routine just got better."
## Localization Notes
- **Formal register** across all languages — use formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted)
- **Cultural adaptation over literal translation** — idioms and playful phrases need local equivalents, not word-for-word translation
- **Load locale-specific keywords** and echo them in the translated notes (each locale has different keywords)
- **Account for text expansion** — some languages expand 30-40% vs. English. Aim for 500-1500 chars in English to leave room.
- **Validate** all translations fit within 4000-char limit
- If translation exceeds the limit, **shorten — never truncate mid-sentence**
## Character Limits
| Field | Limit | Indexed? | Requires Submission? |
|-------|-------|----------|---------------------|
| What's New | 4,000 | No | Yes |
| Promotional Text | 170 | No | No |
SKILL.md
---
name: asc-whats-new-writer
description: Generate engaging, localized App Store release notes (What's New) from git log, bullet points, or free text using canonical metadata under `./metadata`. Optionally pairs with promotional text updates.
---
# asc What's New Writer
Generate engaging, localized release notes from flexible input. Optionally pair with promotional text updates.
## Preconditions
- Metadata pulled locally into canonical files via `asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"`. OR: user provides keywords manually.
- Auth configured for upload (`asc auth login` or `ASC_*` env vars).
- The **primary locale** is `en-US` unless the user specifies otherwise.
## Before You Start
1. Read `references/release_notes_guidelines.md` for tone, structure, and examples.
2. Identify the **latest version directory** under `metadata/version/` (highest semver). Use this for all metadata reads.
3. Enumerate **existing locales** by listing the JSON files in that version directory.
## Phase 1: Gather Input
Accept one of three input modes (auto-detect):
### Git Log
Parse commits since the last tag:
```bash
# Find latest tag
git describe --tags --abbrev=0
# List commits since that tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
```
Filter out noise: merge commits, dependency bumps, CI changes, formatting-only commits. Extract user-facing changes.
### Bullet Points
User provides rough bullets like:
- "improved search"
- "fixed crash on launch"
- "added sleep timer"
### Free Text
User describes changes conversationally:
> "We made search faster, fixed that annoying crash when you open the app, and added a sleep timer feature"
The skill extracts and structures the changes from the text.
### No Input Provided
Prompt the user: "What changed in this release? You can paste git log output, bullet points, or just describe the changes."
## Phase 2: Draft Notes (Primary Locale)
### Step 1: Classify Changes
Group changes into sections per the guidelines:
- **New** — new features or capabilities
- **Improved** — enhancements to existing features
- **Fixed** — bug fixes users would notice
Omit empty sections. If all changes are fixes, only show "Fixed."
### Step 2: Write Benefit-Focused Copy
Follow the tone rules from `references/release_notes_guidelines.md`:
- Describe user impact, not implementation details
- Use direct address ("you") and action verbs
- Be specific — mention concrete improvements
### Step 3: Front-Load the Hook
The first ~170 characters are the only visible part before "more." Lead with the single most impactful change in a complete, compelling sentence.
### Step 4: Echo Keywords for Conversion
1. Read `keywords` from `metadata/version/{latest}/{primary-locale}.json`
- These canonical files are also what `asc metadata keywords ...` reads and writes.
2. If the field is empty or missing, skip this step
3. Identify keywords relevant to the changes being described
4. Weave them naturally into the notes — never force or stuff
### Step 5: Respect Character Limits
- Keep total length between 500-1500 characters in the primary locale
- This leaves room for localized expansions (some languages expand 30-40%)
- Hard limit: 4,000 characters
### Step 6: Optionally Draft Promotional Text
If the user wants it, draft a 170-char promotional text that:
- Summarizes the update's theme in one punchy line
- Can reference seasonal events
- Is updatable without a new submission
### Present Draft
Show the draft to the user with character count. Wait for approval before localizing.
## Phase 3: Localize
Translate the approved notes to all existing locales.
### Translation Rules
- Use formal register and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, Italian: Lei)
- Adapt tone to local market — playful English may need adjustment for formal markets (ja, de-DE)
- Do NOT literally translate idioms — adapt them to local equivalents
- A playful tone in English may need to be more respectful or formal in other cultures
### Locale-Specific Keyword Echo
For each locale:
1. Read `keywords` from `metadata/version/{latest}/{locale}.json`
2. Echo locale-specific keywords naturally in the translated notes
3. If keywords field is empty, skip echo for that locale
### Validate
- All translations must be ≤ 4,000 characters
- Promotional text must be ≤ 170 characters per locale
- If a translation exceeds the limit, shorten it — never truncate mid-sentence
## Phase 4: Review & Upload
### Step 1: Present Summary
Show a table of all locales with their notes and character counts:
```
| Locale | What's New (first 80 chars...) | Chars | Promo Text | Chars |
|--------|-------------------------------|-------|------------|-------|
| en-US | Search just got faster — ... | 847 | New sleep… | 142 |
| ar-SA | البحث أصبح أسرع — ... | 923 | نوم جديد… | 138 |
| ... | ... | ... | ... | ... |
```
### Step 2: Wait for Approval
Do not upload without user confirmation.
### Step 3: Upload
Upload via `asc` (verify exact syntax with `asc --help`):
```bash
# Individual locale direct update
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"
# Bulk canonical-metadata push after writing ./metadata/version/<version>/<locale>.json
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"
```
If promotional text was drafted, either include `--promotional-text "..."` in the direct update command or write `promotionalText` into the canonical JSON before `asc metadata push`.
### Step 4: Handle Failures
On partial upload failure:
- Report which locales succeeded and which failed
- Offer to retry failed locales
## Metadata File Paths
- **Keywords:** `metadata/version/{latest-version}/{locale}.json` → `keywords` field
- **Current What's New:** `metadata/version/{latest-version}/{locale}.json` → `whatsNew` field
- **Latest version:** highest semver directory under `metadata/version/`
- The canonical `./metadata` tree is what `asc metadata pull`, `asc metadata push`, and `asc metadata keywords ...` operate on.
- Follows the same metadata resolution conventions as `asc-aso-audit`
## Notes
- What's New is **not indexed** for App Store search — write for humans, not algorithms.
- Promotional text is the only metadata field updatable without a new submission.
- The 170-char visible window is the most important part of your release notes.
- Each app update triggers algorithm re-evaluation — the act of updating matters, even if the text doesn't affect ranking.
- Ideal update cadence: every 2-4 weeks.
- For full metadata translation (all fields), use `asc-localize-metadata` instead.
- For keyword research and optimization, use `asc-aso-audit` first.
- If the local keyword field is stale before drafting, refresh it with `asc metadata pull` or inspect planned keyword changes with `asc metadata keywords diff`.