Release Notes for Humans

Good release notes respect both sides of the work.

This skill keeps the evidence maintainers need separate from the notes readers see, producing accurate, concise release notes that help people decide whether and how to update.

Workflow

Choose the route that matches the requested result. An explicit change takes precedence when the request also uses review language.

• Existing draft: Treat supplied text or a supplied file as the working draft. Apply the approval gates to a user-supplied or previously approved draft.
• Inferred draft: Honor the user’s explicit change scope, then edit the supplied note target or return a new draft after completing the shared scope and evidence workflow below.
• Review: Keep the task read-only. Report evidence-backed omissions and concrete consistency problems without rewriting the notes, and distinguish defects from intentional or harmless variations.
• Local conventions: Apply this skill’s structure, ordering, and prose rules without inspecting prior release notes or changelog entries. Inspect earlier notes only when they are the requested draft or the user explicitly asks for comparison or consistency.

Whenever a route uses repository evidence or supplied change evidence, resolve the release scope before building the evidence inventory. Treat an explicit user-provided scope as the evidence scope in step 3. It replaces default tag boundary selection and requires a target ref only when the scope is ref-backed. Resolve the release state, release units, package grouping, and affected package mapping from repository or supplied context, then build the inventory for every resolved non-initial scope and continue the selected route through final review and delivery.

Drafting, editing, or reviewing release prose does not authorize publishing a release, creating a tag, bumping a version, committing, pushing, or making any other release mutation. Leave a separately requested operation to the workflow that owns it.