Release Notes

Release Notes

Generate release notes for a release PR. Brief, truth-based, no fabrication.

Configuration

On startup, use the Read tool to load ~/.claude/skills/release-notes/preferences.md.

Tracker-agnostic — works with any issue tracker (Linear, Jira, GitHub Issues, Asana, ClickUp, Shortcut, Plane, Notion, custom). You configure two things: how to detect ticket IDs in PR bodies, and how to link them.

Expected keys:

- ticket-prefix:                     # Optional. Tracker key — e.g., ENG, PROJ, ABC, JIRA. Used to detect IDs as -NNNN. If unset, falls back to the generic regex [A-Z]{2,5}-\d+ (any uppercase prefix + dash + digits).
- ticket-url-template:    # Optional. URL template with literal `{TICKET}` placeholder. Examples:
                                             #   Linear:        https://linear.app/myorg/issue/{TICKET}
                                             #   Jira:          https://myteam.atlassian.net/browse/{TICKET}
                                             #   GitHub Issues: https://github.com/myorg/myrepo/issues/{TICKET}
                                             #   Asana:         https://app.asana.com/0/{TICKET}
                                             #   Shortcut:      https://app.shortcut.com/myorg/story/{TICKET}
                                             #   Plane:         https://app.plane.so/myorg/projects/.../issues/{TICKET}
                                             # If unset, ticket IDs render as bare text without links.

Behavior when keys are missing:

• No ticket-prefix → use the generic regex [A-Z]{2,5}-\d+. Works for most trackers.
• No ticket-url-template → render bare ticket IDs (e.g., Closes ENG-1234.). Mention once at the end: "Set ticket-url-template in preferences.md to enable clickable ticket links."

Hard rules

1. Truth only. Every claim must be sourced from a merged PR's actual title/body. Never invent features, motivations, or impact statements that aren't in the source PRs.
2. Brief. Each PR section is 1–3 sentences max. Cut file enumerations, architecture diagrams, dead-code lists, "what changed" prose blocks. Mirror the source PR's ## Summary, not its full body.
3. Never git add -A and never push the release notes without showing them to the user first and getting explicit approval.
4. No drive-bys. Do not add commentary, suggestions, or "follow-ups" the source PRs didn't flag.

Steps

1. Resolve the release PR

• If $ARGUMENTS is a number → that's the PR.
• Else → gh pr list --base prod --state open --limit 5 --json number,title,headRefName and ask the user which one if multiple, or use the only open one.
• Capture: number, title, baseRefName, headRefName, url.

2. List the squash-merged PRs in the release

gh pr view  --json commits --jq '.commits[].messageHeadline'

Each squash-merged commit headline ends in (#NNN) — extract the PR numbers. If commits is sparse (squash-merge collapsed history), fall back to:

git log origin/..origin/ --oneline

and grep (#\d+) from the headlines.

3. Fetch each child PR

For each PR number, in parallel:

gh pr view  --json title,body,number,url,labels

Extract from each:

• title (use as section heading after stripping conventional-commit prefix if helpful)
• ## Summary paragraph (or first 1-3 sentences of the body if no Summary section)
• Issue-tracker ticket IDs from anywhere in the body — match -NNNN (where TICKET-PREFIX comes from preferences, falling back to [A-Z]{2,5}-\d+). When ticket-url-template is set, substitute {TICKET} to build the link; otherwise render the bare ticket ID.
• PR URL (for the #NNN link, GitHub auto-links)

If a PR's Summary is more than ~3 sentences, halve it, then halve again. Keep only the user-visible/product-visible bits. Cut implementation prose ("service-side normalizers", "Zod widens", file paths) unless that is the product change.

4. Build the body

Template:

## What's in this release

**1.  — #**

Closes []()](...)` if multiple>. If no template configured, render as `Closes .` (no link).

**2.  — #**

Closes [](...).

## How to test

- 
- 

If — and only if — a source PR explicitly flags a follow-up that blocks prod (deploy ordering, flag flip, infra step), add:

## Follow-ups

- 

Otherwise, skip the Follow-ups section. Do not invent follow-ups.

5. Title

Format: Release YYYY-MM-DD —

The theme should name the 1–2 biggest user-visible changes (e.g., "PMI UI + migration cleanup"). Use today's date.

6. Show, then push

Print the full proposed title + body to the user. Then ask:

> Push this to PR #? (yes / edit / no)

• yes → write the body to a temp file, then push via REST (works around the Projects-classic GraphQL deprecation that blocks gh pr edit on this org):

``bash gh api -X PATCH "repos///pulls/" \ -f title="" \ -F body=@/tmp/pr--body.md \ --jq '"OK: " + .title + " — " + .html_url' ` Try gh pr edit first if you prefer; if it errors with Projects (classic) is being deprecated, fall back to the REST call above. The edit *does not* land on the GraphQL failure — always verify via gh pr view --json title --jq .title`.

• edit → ask what to change, regenerate, ask again
• no → leave the PR alone, exit

7. Verify

After push, gh pr view --json title,body --jq '.title' to confirm the edit landed. Report the URL.

Style reminders (drawn from user prefs)

• Cut: file paths, line counts, "Adds/Removes/Migrates" tables, architecture diagrams, Figma node IDs, internal scaffolding details.
• Keep: what changed for the user, what it closes, how to verify it on staging.
• If a source PR is purely internal (refactor, test infra, dep bump) and has no user-visible surface, still list it but flag it as such in one sentence: "Internal — ." No padding.
• If two source PRs are part of the same chunked feature, group them under one numbered section with both #NNN links rather than splitting.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mostafa-drz
• Source: mostafa-drz/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.