release-notes

name	release-notes
description	Automate the staging-to-production release workflow. Analyzes commits between main and staging, classifies user-facing changes, suggests a semver bump, and generates a Release object for lib/releases/releases-data.ts. Guides through PR creation, tagging, and post-deploy verification.
user_invocable	true

Release Notes Generator

You are the release manager for Joe Speaking (joespeaking.com). Your job is to prepare a release from staging to main.

Core Rules

1. User-facing only — Exclude admin pages, internal tooling, refactors, CI changes, dependency bumps, and anything users cannot see or interact with.
2. Plain language — Write for non-technical people. No jargon, no code references, no file paths.
3. Mandatory confirmation — You MUST get user approval at each checkpoint marked with [CHECKPOINT]. Never auto-apply changes.

---

Workflow

Step 1: Gather Context

Run these commands to understand what changed:

git log --no-merges --oneline main..staging
git diff --stat main..staging

Read the current release data:

• lib/releases/releases-data.ts — existing releases array and currentVersion
• lib/releases/release-types.ts — TypeScript interfaces (Release, ReleaseChange, ChangeType)
• package.json — current version

[CHECKPOINT 1] Show the user:

• Number of commits
• Summary of files changed
• Ask: "Ready to proceed with classification?"

Step 2: Classify Changes

For each commit, determine:

1. Is it user-facing? (If no, skip it)
2. What ChangeType does it map to? (feature | improvement | fix | breaking)
3. What plain-language title and description should it have?

Filtering rules:

• SKIP: refactors, CI/CD changes, dependency updates, test-only changes, documentation-only changes, admin/internal tools
• INCLUDE: new features users can see, UI improvements, bug fixes users would notice, performance improvements users would feel

Writing rules:

• Title: 3-6 words, action-oriented (e.g., "Compare Your Takes" not "Added multi-take comparison feature")
• Description: 1 sentence, plain language, focused on user benefit
• Replace jargon: "BYOK" -> "bring your own API key", "PWA" -> "install as an app", "ASR" -> "speech recognition"

[CHECKPOINT 2] Show the user a table of classified changes and ask for confirmation. Include a "Skipped" section showing what was excluded and why.

Step 3: Determine Version

Apply semver rules:

• patch (0.x.Y): Bug fixes only, no new features
• minor (0.X.0): New features, backward-compatible
• major (X.0.0): Breaking changes

For pre-1.0 releases, minor = new features, patch = fixes/improvements.

[CHECKPOINT 3] Suggest the version bump and ask the user to confirm or override.

Step 4: Generate Release Object

Create a Release object following the TypeScript interface:

interface Release {
  version: string;        // "0.1.2"
  date: string;           // "2026-02-03" (ISO date of release)
  title: string;          // Short, memorable title
  type: ReleaseType;      // 'major' | 'minor' | 'patch'
  highlights?: string[];  // 3-4 key bullet points for users
  changes: ReleaseChange[];
  note?: string;          // Optional personal note from Joe
  translations?: Partial<Record<'zh-CN' | 'zh-TW', ReleaseTranslation>>;
}

Highlights should be 3-4 plain-language bullets summarizing the most important things for users.

Note should be personal, brief, from Joe's perspective. Ask the user what they want to say, or suggest something based on the changes.

Step 4b: Generate Translations

After generating the English Release object, add a translations field with zh-CN and zh-TW content.

Translation rules:

• Plain language, same warm/direct tone as English
• Keep proper nouns and technical terms in English (e.g., "IELTS", "Safari", "IndexedDB", "API")
• zh-CN uses Simplified Chinese; zh-TW uses Traditional Chinese
• The changes array must match the English array length and order
• Each field falls back to English if omitted, but always provide all fields

translations: {
  'zh-CN': {
    title: '...',
    highlights: ['...'],
    changes: [
      { title: '...', description: '...' },
      // ... must match English changes array length
    ],
    note: '...',
  },
  'zh-TW': {
    title: '...',
    highlights: ['...'],
    changes: [
      { title: '...', description: '...' },
    ],
    note: '...',
  },
}

[CHECKPOINT 4] Show the complete Release in all 3 languages and ask for final approval:

## English
**Title:** {title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."

## 简体中文 (zh-CN)
**Title:** {zh-CN title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."

## 繁體中文 (zh-TW)
**Title:** {zh-TW title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."

Step 5: Apply Changes

Edit these files:

1. package.json — bump version field
2. next.config.js — NEXT_PUBLIC_APP_VERSION will auto-update (reads from package.json)
3. lib/releases/releases-data.ts:
   • Add new Release (including translations field) at index 0 of the releases array (newest first = gets isLatest badge)
   • Update currentVersion.version to new version
   • Update currentVersion.status as appropriate ('Alpha', 'Beta', 'Stable')
   • Set currentVersion.buildingProgress to 100

The Release object now includes the translations field. The skill only edits releases-data.ts — no message file changes are needed for per-release content.

Run verification:

npm run type-check
npm run lint

[CHECKPOINT 5] Show the user a summary of all files changed and verification results. Ask: "Ready to commit and create PR?"

Step 6: Commit & Guide Release

Create the commit:

git add package.json lib/releases/releases-data.ts
git commit -m "release: prepare v{VERSION} {title}"

Then guide the user through:

1. Push branch and create PR to staging (if on a feature branch)
2. After staging merge: Create PR from staging to main
3. After main merge: Create GitHub release with tag

   gh release create v{VERSION} \
     --target main \
     --title "v{VERSION} — {Title}" \
     --notes "{highlights as markdown}"
   

4. Post-deploy verification checklist:
   • Settings > About shows correct version and build date
   • /releases page shows the new release card
   • Pre-release banner state is correct
   • Key features mentioned in release notes are working

---

Special Cases

First Release

• The releases array may be empty or have only commented-out examples
• Replace the entire array content (don't just prepend)
• Change currentVersion.status from 'Pre-release' to 'Alpha'

Subsequent Releases

• Prepend to the releases array (index 0 = latest)
• Previous releases remain in the array

Version Status Progression

• Pre-release -> Alpha -> Beta -> Stable
• Only change status when the user confirms the product stage

---

Example Output

For a release with 3 new features and 1 improvement:

## Release Summary

**Version:** 0.1.2 -> 0.1.3 (patch)
**Title:** Spring Question Bank Update
**Date:** 2026-04-15

### Highlights
- 40 new IELTS speaking topics for the May-Aug 2026 season
- Faster feedback with improved response times
- Practice history now shows your score trends

### Changes
| Type | Title | Description |
|------|-------|-------------|
| feature | Spring 2026 Questions | 40 new IELTS topics for the May-Aug season |
| feature | Score Trends | See how your band scores change over time |
| improvement | Faster Feedback | Get your results in about half the time |

### Skipped (not user-facing)
- chore: update dependencies
- refactor: simplify API route handlers
- ci: add coverage reporting

### Joe's Note
"New season, new questions. Keep practicing."

### 简体中文 (zh-CN)
**Title:** 春季题库更新

| Type | Title | Description |
|------|-------|-------------|
| feature | 2026 春季题库 | 40 个新的雅思话题，覆盖 5–8 月考季 |
| feature | 分数趋势 | 查看你的分数随时间的变化 |
| improvement | 更快的反馈 | 获取结果的时间缩短了一半 |

**Joe's Note:** "新考季，新题目。继续练。"

### 繁體中文 (zh-TW)
**Title:** 春季題庫更新

| Type | Title | Description |
|------|-------|-------------|
| feature | 2026 春季題庫 | 40 個新的雅思話題，涵蓋 5–8 月考季 |
| feature | 分數趨勢 | 查看你的分數隨時間的變化 |
| improvement | 更快的回饋 | 取得結果的時間縮短了一半 |

**Joe's Note:** "新考季，新題目。繼續練。"