SkillScan: pass
Release notes from merged PRs since last tag
Collects merged PRs and commits since the last tag, classifies by user impact, rewrites in user vocabulary, and adds upgrade steps.
Add a trust badge to your README
[](https://waxmark.app/items/release-notes/scan)
---
name: release-notes
description: Turns the merged pull requests and commits since the last git tag into user-facing release notes grouped by impact (breaking, new, improved, fixed, security, internal), with upgrade steps. Use when the user asks to write release notes, draft a changelog entry for a version, prepare a GitHub release, or summarize what shipped since the last release.
license: CC0-1.0
allowed-tools: Bash(git tag *) Bash(git describe *) Bash(git log *) Bash(gh pr list *) Bash(gh pr view *) Bash(gh release *)
metadata:
author: Waxmark
version: "1.0.0"
---
# Release Notes
Release notes are written for the person upgrading, not the person who wrote the code. Every line answers "what changes for me?"
## Procedure
1. **Find the range.**
```bash
LAST=$(git describe --tags --abbrev=0)
echo "$LAST"
git log --oneline --merges "$LAST"..HEAD
git log --oneline --no-merges "$LAST"..HEAD
```
If there is no tag, ask for the previous release commit or date. If the repo squash-merges, the non-merge log is the PR list.
2. **Pull PR metadata** when `gh` is available; PR titles and labels are usually better than commit subjects.
```bash
gh pr list --state merged --search "merged:>$(git log -1 --format=%cI "$LAST")" --limit 200 \
--json number,title,labels,author,body,url
```
For PRs whose title is unclear, read the body with `gh pr view <n> --json body`.
3. **Classify** each item into exactly one section. Decide by user impact, not by commit type: a `refactor` that changes a default is **Breaking**; a `feat` that only adds an internal metric is **Internal**.
4. **Rewrite** each line in the user's vocabulary. Start with the capability or the problem, not the implementation. Drop PR noise ("bump", "wip", "fix lint") into Internal or omit.
5. **Write upgrade steps** for every Breaking item: what to change, with a before/after snippet when it fits on two lines.
6. **Verify** by re-reading the merge list: every PR is either in the notes or consciously omitted. Count both and report.
## Output template
```markdown
# <project> <version> - <YYYY-MM-DD>
<One or two sentences: the theme of this release and the headline change.>
## Breaking changes
- **<What breaks>.** <Why.> Upgrade: <exact step>. (#123)
## New
- <Capability, from the user's point of view>. (#124)
## Improved
- <Existing behavior, now better how>. (#125)
## Fixed
- <Symptom the user saw> no longer happens when <condition>. (#126)
## Security
- <Issue class> in <component>; <versions affected>; <CVE or advisory id if any>. (#127)
## Internal
- <Dependency bumps, CI, refactors - one line each or a single summary line>
## Upgrade notes
1. <Ordered steps, including migrations and config changes>
Full diff: <compare URL, e.g. https://github.com/OWNER/REPO/compare/<last>...<new>>
Contributors: @a, @b (first-time: @c)
```
Omit empty sections. Keep each bullet to one sentence; link the PR number at the end.
## Style rules
- Present tense, active voice: "Exports now include archived items", not "Added support for exporting archived items".
- Name the user-visible surface (CLI flag, API field, UI screen), not the file or function.
- Numbers over adjectives: "Cold start drops from 3.1s to 0.9s", not "much faster".
- Version bump suggestion: Breaking -> major, New -> minor, otherwise patch (for pre-1.0 projects, Breaking -> minor). State it with the reason.
## Example line rewrites
| Commit / PR title | Release note |
|---|---|
| `fix(parser): handle CRLF in frontmatter` | Files with Windows line endings no longer fail to parse frontmatter. (#88) |
| `feat: add --json flag to list cmd` | `list --json` prints machine-readable output for scripting. (#91) |
| `refactor: default timeout 30s -> 10s` | **Default request timeout is now 10s** (was 30s). Upgrade: set `timeout: 30000` to keep the old behavior. (#95) |