---
name: release-notes
description: >-
  Generates clear, user-facing release notes from commit history, changelogs, and
  code diffs. Use when publishing a software release, announcing features, or
  writing version update summaries.
  NOT for internal changelogs, commit message cleanup, or deployment runbooks.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** haiku
**Scope:** Git history, changelog files, issue trackers, PR descriptions, code diffs
**Off-limits:** Modifying code, publishing releases, pushing tags, sending announcements
### Hard Rules
- No credentials in output or git — ever
- No publishing content without explicit user approval
- No deleting files — archive first, 48hr hold
- Report completion to boss via structured output
## Essential Principles
1. **Lead with user value** — Describe what users gain, not what developers built. "Search loads 3x faster" beats "Refactored query optimizer." Guards against: notes nobody reads.
2. **Breaking changes get maximum visibility** — Own section with migration steps. Guards against: users discovering breakage after upgrading.
3. **Every feature links to documentation** — No doc link = incomplete note. Guards against: excited users with no way to learn the feature.
4. **Verify against actual changes** — Cross-reference notes against commit/PR history. Guards against: hallucinated features or missing fixes.
## When to Use
- Writing release notes for a new software version
- Summarizing changes between two tags or commits
- Creating feature launch announcements from technical changes
- "Write release notes for v2.0" / "What changed since last release?"
## When NOT to Use
- Internal developer changelogs — use commit conventions instead
- Deployment runbooks — use `migration-planning` instead
- Cleaning up commit messages — use git workflow skills instead
- Marketing copy — use communications/copywriting skills instead
- Detailed API change docs — use `api-documentation` instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll list commit messages as release notes" | Commits are for developers, not users — translation is the point |
| "Breaking changes can go in improvements section" | Hidden breaking changes cause failures and erode trust |
| "I'll skip the upgrade guide since it's obvious" | Obvious to developer != obvious to user |
| "Internal refactoring doesn't need mention" | If it affects performance or behavior, users care |
| "PR titles are enough, I don't need the diff" | PR titles are summaries — diffs reveal actual scope |
## Workflow
### Phase 1: Change Discovery
**Entry:** User has specified a version, tag range, or commit range
**Actions:**
1. Run `git log` between the specified range to collect all commits
2. Read PR descriptions and linked issues for context
3. Grep for version bumps in dependency manifests and config files
4. Identify breaking changes (removed/renamed exports, changed APIs, migration files)
5. Categorize: new features, improvements, bug fixes, breaking changes, deprecations
**Exit:** Categorized list of all changes with source references
### Phase 2: Note Drafting
**Entry:** Categorized change list exists
**Actions:**
1. Write 1-2 sentence highlight of the most impactful change
2. Write each feature note in user-value language
3. Write breaking changes with explicit migration steps
4. Write bug fixes referencing the symptom resolved (not internal cause)
5. Add documentation links for every new feature
6. Write upgrade instructions from the previous version
**Exit:** Complete release notes draft
### Phase 3: Verification
**Entry:** Release notes draft complete
**Actions:**
1. Cross-reference every note against commit/PR history — confirm nothing fabricated
2. Verify no changes from the range are omitted (especially breaking changes)
3. Confirm every new feature has a doc link or "docs pending" note
4. Check breaking changes include migration steps
5. Validate version numbers and dates are correct
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "release-notes",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Release notes for v1.0.1: 2 features, 5 improvements, 8 fixes, 1 breaking change.",
  "findings": [
    {"item": "Breaking: /api/search response format changed", "severity": "critical", "detail": "Flat array to paginated object. Migration guide included."},
    {"item": "New: Batch memory import", "severity": "info", "detail": "Import from JSON files. Doc link included."},
    {"item": "Missing docs for webhook retry", "severity": "medium", "detail": "Feature noted but no doc page exists. Marked pending."}
  ],
  "artifacts": ["RELEASE_NOTES_v1.0.1.md"],
  "change_counts": {"features": 2, "improvements": 5, "bug_fixes": 8, "breaking_changes": 1},
  "errors": [], "elapsed_seconds": 35.7
}
```
### Bad Example
```json
{"skill": "release-notes", "summary": "Release notes written", "findings": [{"item": "Notes created", "severity": "info", "detail": "Covers all changes"}]}
```
Wrong: No change counts, no breakdown, no mention of breaking changes or missing docs.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] Breaking change discovered with no clear migration path
- [ ] Security fixes that may need coordinated disclosure
- [ ] Cannot determine correct version number or tag range
- [ ] More than 30% of commits have no PR description or context
- [ ] Credentials or secrets in commit diffs
- [ ] Release notes need publishing (requires explicit approval)

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] All commits in range accounted for in notes
- [ ] Changes categorized (features, improvements, fixes, breaking, deprecations)
- [ ] Breaking changes have own section with migration steps
- [ ] Every new feature references docs (or flags pending)
- [ ] Notes in user-value language, not developer jargon
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
