release

name	release
description	Drafts style-compliant release notes by summarizing the pull requests merged since the previous release. Infers and recommends the release type (major, minor, or patch) for the user to confirm, then produces a numbered list of the most impactful changes. Includes a sibling-library compatibility statement for cross-dependent library sets only. Use when preparing a release, drafting release notes, or when the user invokes /release.
user-invocable	true

Release

Drafts style-compliant release notes summarizing the pull requests merged since the previous release.

---

Scope

Covers:

• Identifying the previous release and the pull requests merged since then
• Inferring and recommending the release type (major, minor, patch) for user confirmation
• Drafting release notes with a numbered list of the most impactful changes
• Including a sibling-library compatibility statement for cross-dependent library sets

Does not cover:

• Creating tags, GitHub releases, or publishing (the user does this)
• The ## What's Changed and **Full Changelog** sections (GitHub generates these automatically on release)
• Committing, pushing, or opening pull requests (see /commit and /pr)

---

Workflow

You MUST follow these steps exactly when this skill is invoked.

Step 1: Gather context

Run the following git commands using the Bash tool:

1. Identify the previous release tag with git tag --sort=-v:refname (most recent first) or git describe --tags --abbrev=0.
2. List the pull requests merged since that tag with git log <previous-tag>..HEAD --merges --format='%h %s%n%b'. The Merge pull request #N from ... subject line names only the number and source branch, while the pull request title and description live in the commit body, so you MUST read the body (not --oneline) to draft the notes.
3. Review the aggregate change scope with git diff <previous-tag>..HEAD --stat.

If --merges returns few or no results relative to the git diff --stat scope, the repository likely uses squash- or rebase-merged pull requests or direct commits to the default branch, which produce no merge commit. Enumerate from git log <previous-tag>..HEAD --oneline --no-merges instead and reconcile both so no merged work is silently dropped.

If the repository has no prior release tag, summarize the full history (git log --merges --format='%h %s%n%b') and note that this is the first release.

Step 2: Determine the dependency model

Determine whether the project is an independent library or part of a unified, cross-dependent library set:

• Cross-dependent set: the project ships as one of a unified set of sibling libraries released and versioned together, so the release notes MUST include a compatibility statement (Step 4).
• Independent library: the project (like the ataraxis libraries) has no enforced cross-dependency web, so the release notes MUST NOT include a compatibility statement.

Step 3: Infer and recommend the release type

Infer the release type from the change set and recommend it to the user. You MUST ask the user to confirm the type before finalizing the notes. The user decides the type, so never decide it unilaterally.

For C++ PlatformIO libraries the release version is single-sourced from library.json rather than pyproject.toml, which is where Python projects hold it. See /platformio-config.

Type	Use case
Major	Breaking API changes, removals, re-licensing, or migrations requiring downstream updates
Minor	New, backward-compatible features or capabilities
Patch	Bug fixes and minor corrections with no new features

Step 4: Resolve the compatibility statement (cross-dependent sets only)

For cross-dependent releases, the compatibility statement names the sibling-library versions this release is designed to work with. You cannot reliably infer these, so ask the user to confirm the compatible sibling-library versions and include them verbatim. For independent libraries, skip this step entirely.

Step 5: Draft the release notes

Produce the release notes following the format below. Present the draft to the user. The user creates the tag and GitHub release manually.

---

Format

### {Major|Minor|Patch} Release

[cross-dependent sets only] This release is designed to work with <sibling-library> vN, <sibling-library> vM, ...

**Major Changes:**

1. <Most impactful change, past tense, descriptive sentence.>
2. <Next change.>

Rules

• The first line is ### {type} Release using the user-confirmed type.
• For cross-dependent releases, follow the header with a single compatibility sentence naming the confirmed sibling-library versions. Omit this line entirely for independent libraries.
• **Major Changes:** introduces a numbered list (1., 2., …) of the most impactful changes, ordered from most to least impactful.
• Each item is a complete, descriptive sentence in past tense (see the verb set in /commit) ending with a period.
• Each item occupies one line, under the line-break rule /commit defines. GitHub soft-wraps the release body, so a hand-wrapped item renders as a rigid block.
• Condense many pull requests into a few impactful themes. Do NOT list every pull request.
• Do NOT include a ## What's Changed section or a **Full Changelog** line. GitHub generates these automatically when the release is published.

Prose punctuation and positive description

Prose uses only the full stop and the comma to separate clauses. Do not use a semicolon or an em-dash (--, —, or –) as a separator, and use a colon only where it is lexically appropriate. A single hyphen stays available as a list marker, in tables, and in compound words. A -- naming a CLI flag or an argument separator, like any token inside a code span, is not a clause separator and is left as written. State what the subject does and what is currently true. Do not frame it by what it is not or what it used to be, and keep a "not Y" contrast only when it is load-bearing because it corrects a counter-intuitive assumption, giving its reason.

Examples

Good (independent library, no compatibility statement):

### Major Release

**Major Changes:**

1. Re-licensed the library to Apache 2.0.
2. Added MCP assets and a companion plugin that enables AI agent interfacing with all library components.
3. Added a log processing (data extraction) pipeline.

Good (cross-dependent set, compatibility statement included):

### Minor Release

This release is designed to work with `acquisition` v5, `behavior` v3, and `analysis` v1.

**Major Changes:**

1. Added shared project and animal data-hierarchy assets for walking the project tree without SessionData.
2. Introduced the data root as a fourth persistent host setting, with MCP tools and CLI commands to manage it.

---

Content rules

The release notes follow the content rules /commit defines for commit messages. They describe ONLY the changes themselves, and /commit carries the forbidden-content list that applies here verbatim.

What and why, not how: Each item states what the release changed and why, not how, and is specific and descriptive rather than vague like "Updated various modules".

Sentence length: Every sentence in a release note item stays under 40 words, broken at a natural clause boundary or split into two numbered items when it runs longer.

Typo-free and grammatical: The release notes must be free of typos and grammatical errors, with every symbol name, file name, and version string verified against the diff or tag output rather than recalled from memory.

---

Related skills

Skill	Relationship
/commit	Provides the past tense verb set and the content rules reused here
/pr	Drafts the per-branch pull request summaries that releases aggregate
/explore-codebase	Provides project context that helps write accurate summaries
/platformio-config	Owns library.json whose version field is the C++ library release version
/pyproject-style	Owns pyproject.toml whose version field is the Python release version

---

Proactive behavior

When the user signals that a release is imminent (a version bump, "preparing a release", or similar), proactively offer to draft release notes. For example: "Would you like me to draft release notes for this version?"

Do NOT create tags or GitHub releases. Present the drafted notes for the user to use manually.

---

Verification checklist

You MUST verify the release notes against this checklist before presenting them to the user.

Release Notes Compliance:
- [ ] First line is `### {Major|Minor|Patch} Release` with the user-confirmed type
- [ ] Release type was recommended AND confirmed by the user
- [ ] Compatibility statement included for cross-dependent releases, omitted for independent libraries
- [ ] Sibling-library versions confirmed by the user (cross-dependent sets only)
- [ ] `**Major Changes:**` numbered list ordered from most to least impactful
- [ ] Each item is past tense and ends with a period
- [ ] Each item occupies one line, with no hand-wrapped continuation
- [ ] Each item describes *what* changed and *why*, not *how*, and is specific rather than vague (not "Updated
      various modules")
- [ ] Prose separators are full stops and commas only, no semicolons or em-dashes (colons, hyphen bullets, and code
      syntax exempt)
- [ ] Prose states what the release does, not what it is not or used to be (contrast only when load-bearing)
- [ ] Every sentence in the drafted text stays under 40 words
- [ ] Free of typos and grammar errors, with every symbol name, file name, and version string verified against the diff
      or tag output rather than recalled from memory
- [ ] Condenses many pull requests into a few impactful themes (does not list every pull request)
- [ ] Does NOT include `## What's Changed` or `**Full Changelog**`
- [ ] Enumerated changes since the previous release tag, reconciling merge and squash/rebase history against the
      `--stat` scope
- [ ] Contains NO authorship details, co-author tags, or attribution
- [ ] Contains NO references to tools or AI unless explicitly requested by the user
- [ ] Contains ONLY information about the changes themselves
- [ ] Did NOT create a tag or GitHub release