Release Notes

Release Notes Skill

Trigger

"Generate release notes" / "Prepare release" / "What changed since last release?"

Steps

1. Identify Release Range

# Find the last tag
git describe --tags --abbrev=0

# List commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

Conditional: No Tags Found

> If no tags found → ask user for the commit range to use.

2. Categorize Changes

Parse commit messages using conventional commit prefixes:

| Prefix | Category | Show In Notes | |--------|----------|---------------| | feat | New Features | ✅ Always | | fix | Bug Fixes | ✅ Always | | perf | Performance | ✅ Always | | docs | Documentation | ✅ If significant | | refactor | Internal | ⚠️ Only if user-visible | | test | Tests | ❌ Skip | | chore | Maintenance | ❌ Skip | | ci | CI/CD | ❌ Skip |

3. Check CHANGELOG

Read CHANGELOG.md for additional context:

• Are there entries not yet in the CHANGELOG?
• Does the CHANGELOG match the git history?

4. Generate Release Notes

Format for GitHub Release:

## What's New

### Features
- **Feature name**: brief description (#PR)

### Bug Fixes
- Fix description (#PR)

### Performance
- Improvement description (#PR)

## Breaking Changes
- (list any breaking changes with migration steps)

## Contributors
- @username (N commits)

5. Verify

• [ ] All features from this release are listed
• [ ] No unreleased features included
• [ ] Breaking changes have migration instructions
• [ ] Commit references are correct

Safety Rules

• NEVER fabricate changes not in the git log
• ALWAYS flag breaking changes prominently
• Include migration steps for any breaking change
• Ask for human review before publishing

Temper Guards

| Shortcut | Why It Breaks | |----------|--------------| | "The commit messages are good enough" | Commit messages are for developers. Release notes are for users — different audience, different detail level. | | "Nobody reads release notes" | Users, support teams, and auditors rely on release notes. Missing notes cause support tickets and compliance gaps. | | "I'll write them after release" | Post-release notes are always incomplete. Context fades fast — write them while the work is fresh. |

Warning Signs

• Release notes don't mention breaking changes — API or behavior changes not flagged
• Version number missing or inconsistent — notes reference wrong version or omit it
• No link to CHANGELOG — notes generated but not persisted to the project's changelog
• New features undocumented — features merged but not mentioned in notes
• Generated from wrong commit range — notes include changes from a different release cycle

Exit Proof

After completing this skill, confirm:

• [ ] Version number present and matches the release tag
• [ ] Breaking changes explicitly documented with migration guidance
• [ ] Generated from actual git history (git log range verified)
• [ ] CHANGELOG.md updated with the new entry
• [ ] All merged PRs and features accounted for in the notes

Persistent Memory (if OpenBrain is configured)

• Before generating notes: search_thoughts("release", project: "", created_by: "copilot-vscode", type: "decision") — load prior release decisions, breaking change precedents, and versioning conventions
• After release notes are finalized: capture_thought("Release: v — ", project: "", created_by: "copilot-vscode", source: "skill-release-notes") — persist release history for future changelog continuity

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: srnichols
• Source: srnichols/plan-forge
• License: MIT

Install and usage instructions live in the source repository linked above.