release-notes

Release Notes Skill

You are generating release notes for the most recent release of a GitHub repository. The goal is a clean, human-readable Markdown summary of what changed — the kind of thing you'd send to stakeholders or post in a changelog.

Inputs

The user will provide a GitHub repo — either as a full URL (https://github.com/owner/repo) or an owner/repo string. Extract the owner/repo identifier from whatever they provide.

If the user specifies a product name to use in the title, use that. For the dimagi/commcare-connect repo, the product name is "Connect" (not "CommCare Connect").

Terminology

When writing user-facing release notes, use the correct user-facing terms — not internal code names:

Use this	Not this
PersonalID	ConnectID

If you encounter other code-level identifiers in PR titles or bodies, use your judgment: if it reads like an internal variable name or database field rather than a product concept, rephrase it into plain language.

Step 1: Find the releases

gh release list --repo <owner/repo> --limit 5

Identify the latest release (most recent) and the previous release (the one before it). Note the tag names and published dates of both.

Step 2: Find merged PRs between the releases

Use the published dates of the two releases to filter merged PRs:

gh pr list \
  --repo <owner/repo> \
  --state merged \
  --search "merged:YYYY-MM-DD..YYYY-MM-DD" \
  --json number,title,author,mergedAt,labels \
  --limit 100

Use the previous release date as the start and the latest release date as the end.

Step 3: Fetch PR details

For each PR, fetch the title and body to understand what it does:

gh pr view <number> --repo <owner/repo> --json title,body,labels

Read the body — not just the title — to get the actual description of what changed. The first few sentences of the body (often under a "Product Description" or similar heading) are usually the most useful.

Batch these requests efficiently — there's no need to fetch one at a time if you can parallelize.

Step 4: Categorize and group

Assign each PR one of these categories based on what it does:

• New — A brand-new feature or capability that didn't exist before
• Improvement — An enhancement, refinement, or extension of something existing
• Fix — A bug fix or correction
• Infra — Infrastructure, performance, configuration, or DevOps changes
• Docs — Documentation-only changes

Then group related PRs into logical sections by feature area (e.g., "Work Areas", "Notifications & Email", "Reporting"). If several PRs all touch the same feature, they belong in the same section. A section with only one item is fine. Don't force unrelated things together.

Skip PRs that are purely internal (e.g., dependency bumps, version bumps, CI config) unless they're meaningful to users.

Step 5: Write the release notes

Use this format:

# Release Notes — {Product Name} v{version}
*Released {date}*

---

## {Section Name}

**`New`** **Feature Title** — One or two sentence description of what changed and why it matters. [Screenshots](PR_URL)

**`Improvement`** **Feature Title** — Description.

---

## {Section Name}

**`Fix`** **Feature Title** — Description.

Guidelines:

• Feature Title: A short noun phrase describing the change (not the PR title verbatim — rephrase if needed to be user-facing).
• Description: Write for a non-technical stakeholder. What does the user now see or experience? Avoid implementation details unless they matter to the user. Keep it to one or two sentences.
• Links: If a PR has screenshots in its body, add [Screenshots](PR_URL). If there are relevant Confluence/docs links you know about, add them too. Don't make up links.
• Order: Lead with the most impactful / user-visible sections. Bug fixes and infra go at the end.

Step 6: Save the output

Save the file to ./outputs/release_notes_{version}.md, creating the outputs/ directory if it doesn't exist.

Then tell the user the file path where the notes were saved.