# Release Notes

> Draft release notes for shipped features

- Skill: `bromso/release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bromso/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bromso/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bromso (https://skillmd.com/u/bromso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bromso/release-notes

---


# Release Notes

Draft release notes for "$ARGUMENTS". List all shipped features with user-facing descriptions, note breaking changes and migration steps, list known issues, and organize by category.

## Prerequisites

Check that `.project/$ARGUMENTS/00-initiate.md` exists. If it does not, tell the user to run an Initiate skill first (e.g., project-charter) and stop.

If the user passes `--skip-checks`, skip the prerequisite check and log the skip to `.project/$ARGUMENTS/skip-log.md` with a timestamp and reason.

## Process

1. **Read existing context:**
   - Read `.project/$ARGUMENTS/00-initiate.md` for project context and product vision
   - Read `.project/$ARGUMENTS/03-review.md` if it exists (for sprint review and completed stories)
   - Read `.project/$ARGUMENTS/02-sprint.md` if it exists (for sprint state and delivery details)
   - Read `.project/$ARGUMENTS/01-plan.md` if it exists (for backlog, story descriptions, and acceptance criteria)

2. **List all features shipped in the release/sprint:**
   - Gather all completed stories from the sprint review or sprint backlog
   - Include bug fixes that were resolved in this release
   - Include improvements or enhancements to existing features
   - Exclude internal-only changes (refactoring, test improvements, CI changes) unless they affect users
   - Note the version number and release date

3. **Write user-facing descriptions for each feature:**
   - Write in benefit-focused language: what the user can now do, not how it was implemented
   - Use plain language — avoid internal jargon, code references, or ticket numbers
   - Keep each description to 1-2 sentences
   - Include examples or before/after comparisons where they clarify the change
   - For technical features, explain the user-visible impact ("Faster page loads" not "Optimized database queries")

4. **Note breaking changes and migration steps:**
   - List any changes that break existing behavior, APIs, or integrations
   - For each breaking change, explain: what changed, why it changed, and what users need to do
   - Provide step-by-step migration instructions if applicable
   - Note the deprecation timeline if old behavior is being phased out gradually
   - Mark breaking changes prominently so they are not missed

5. **List known issues and workarounds:**
   - List any known bugs or limitations in this release
   - For each known issue, provide a workaround if one exists
   - Note which issues are planned to be fixed in the next release
   - Be honest about known issues — users trust transparency more than perfection

6. **Group by category:**
   - Organize release notes into clear categories:
     - **New Features** — entirely new capabilities
     - **Improvements** — enhancements to existing features
     - **Bug Fixes** — resolved issues
     - **Breaking Changes** — changes requiring user action
     - **Known Issues** — current limitations with workarounds
   - Within each category, order by user impact (most impactful first)

7. **Add version number and date:**
   - Include the version number (e.g., v1.2.0) following semantic versioning if applicable
   - Include the release date
   - If this is a pre-release or beta, note the stability level
   - Reference the previous version for context ("Changes since v1.1.0")

8. **Write the artifact** — append to `.project/$ARGUMENTS/03-review.md` under a `## Release Notes` section:
   - **Version & Date** — version number, release date, previous version reference
   - **New Features** — user-facing descriptions of new capabilities
   - **Improvements** — enhancements to existing features
   - **Bug Fixes** — resolved issues with brief descriptions
   - **Breaking Changes** — changes requiring user action with migration steps
   - **Known Issues** — current limitations with workarounds

## Output

Release notes appended to `.project/$ARGUMENTS/03-review.md`. Present a summary highlighting:
- Version number and release date
- Number of new features, improvements, and bug fixes
- Any breaking changes requiring user action
- Number of known issues
- Overall release theme (one sentence describing the release focus)