Release Notes

Core Question

What user-facing release-note text is supported by the available evidence, and what limitations must be disclosed?

When To Use

Use this skill when the user asks to:

• draft release notes,
• summarize changes for a release,
• turn changelog entries into a release announcement,
• draft a GitHub release body as text,
• identify highlights, fixes, breaking changes, migrations, deprecations, or known issues,
• locally update a release-note file when explicitly requested.

When Not To Use

Do not use this skill to create Git tags, publish hosted releases, call release APIs, push files, change versions, or edit changelog structure.

Route to:

• tag-release for Git tag creation.
• a future publish-release skill or manual workflow for hosted release publication.
• version-bump for version changes.
• changelog-maintenance for changelog file maintenance.
• conventional-commits for commit message work.

Required Evidence

Inspect or establish:

• release range or previous/current tag,
• changelog entries,
• commit log and PR/issue references when available,
• version number and release date when provided or evidenced,
• breaking changes and migration notes,
• security/performance evidence before claiming those categories,
• known issues only when evidenced,
• target audience and output format when relevant.

Operating Contract

This skill drafts or locally updates release-note text only. It does not create Git tags, publish hosted releases, call GitHub Releases APIs, push files, or change version files.

You MAY:

• inspect changelog, commit log, PR/issue references, and release artifacts,
• draft release-note text,
• locally edit a release-note file when explicitly requested,
• restructure release-note text for audience and clarity.

You MUST:

• make release notes evidence-bound,
• separate user-visible changes from internal noise,
• make breaking changes and migration notes prominent,
• omit or qualify unsupported security/performance claims,
• disclose missing release range or evidence gaps,
• verify local file diffs when editing.

You MUST NOT:

• publish hosted releases,
• create Git tags,
• push files,
• change version files,
• invent release dates, PR numbers, issue IDs, security fixes, performance improvements, or known issues.

State / Risk Table

Workflow

1. Identify audience, output format, and whether mutation is requested.
2. Inspect release range, changelog, commits, PRs/issues, and version evidence.
3. Classify evidence quality and missing information.
4. Draft notes with user impact first.
5. Highlight breaking changes, migration notes, deprecations, and known issues when evidenced.
6. Remove unsupported claims.
7. If editing a local file, inspect diff and verify only requested file changed.
8. Report evidence, assumptions, verification, and limitations.

Decision Rules

• Prefer user impact over implementation detail.
• Do not list every commit when it creates noise.
• Do not claim security or performance improvement without security-relevant or performance evidence.
• Do not invent migration notes; state when none were evidenced.
• Do not publish hosted releases or tags.
• Draft GitHub release body as text only unless a future publication skill owns the API mutation.

Tool Rules

Allowed:

• read changelog, commits, PR/issue references, and version files,
• produce text artifacts,
• edit a local release-note file only when explicitly requested.

Forbidden:

• Git tag creation,
• hosted release publication,
• GitHub Releases API mutation,
• package publication,
• pushing files,
• version-file mutation.

Verification

Minimum verification:

• R1: self-check all claims against evidence.
• R2: inspect local diff and confirm only requested release-note file changed.

Verify:

• highlights are supported,
• breaking changes are not hidden,
• security/performance claims are evidenced or omitted,
• internal-only changes are not overemphasized,
• missing range or data is disclosed.

Output Contract

Final response should include:

## Result

- Release-note text or file update summary.

## Evidence

- Range, changelog, commits, PRs/issues, version used.

## Verification

- Claim self-check and diff check if mutated.

## Limitations

- Missing evidence, unverified claims, or publication out of scope.

Stop / Confirmation Rules

Stop when release range, audience, or evidence is missing in a way that would make notes misleading.

Requires explicit user intent for local file mutation. Route Git tags, hosted release publication, package publication, version changes, and remote/shared mutation out of this skill.

Lazy-load References

Load:

• references/audience-rules.md when tone or audience is unclear.
• references/templates.md when output format is requested.
• references/evidence-sources.md when range/source choice is unclear.
• references/examples.md when the user asks for examples.
• references/failure-modes.md for unsupported claim risks.
• references/verification.md for evidence checks.