Obot Release Notes Drafter

Draft Release Notes

Drafts release notes for the next obot minor release and creates a draft (unpublished) GitHub release containing them. The release stays in draft state for the user to review, edit, and publish themselves. Never creates the git tag, never publishes the release, never pushes anything.

Inputs

• Target version (e.g. v0.22.0): ask the user if not provided. If recent pre-release tags exist (e.g. v0.22.0-rc3), suggest the corresponding minor (v0.22.0) and confirm.
• Diff baseline (e.g. v0.21.3): auto-detect as the highest non-pre-release tag, regardless of whether it is a minor or patch, that is also an ancestor of HEAD. This is the range used to find changes (<DIFF_BASELINE>..HEAD) and the left side of the "Full Changelog" compare link. Use git tag --sort=-v:refname | grep -v -- '-' | head -1, then verify with git merge-base --is-ancestor <candidate> HEAD. Patch releases are sometimes cut from a separate release branch that never merges back into main — if the highest-sorted tag fails the ancestor check, walk down to the next-highest tag and check again until one passes. Do not silently trust version-sort order alone.
• Style reference (e.g. v0.21.0): auto-detect as the highest vX.Y.0 tag that is not a pre-release. Use git tag --list 'v*.*.0' --sort=-v:refname | grep -v -- '-' | head -1. This release's notes are the tone/structure template. It is often the same as the diff baseline but may differ when patch releases exist between minors.

Hard constraints

• Do NOT create git tags. Do NOT run git tag or git push --tags. The draft release does not require the tag to exist locally — GitHub creates it only when the draft is published, which the user does manually.
• gh release create is allowed ONLY with --draft. Never run it without --draft. Never run gh release edit --draft=false. Never publish.
• Do NOT model the notes on patch releases (vX.Y.Z where Z > 0) or pre-releases (-rc, -alpha, -beta). Those use minimal notes. Always model on the most recent vX.Y.0.
• No emojis. No em dashes (—). Use plain hyphens or rewrite the sentence. No "we're thrilled / excited to / proud to" beyond the one opening line the template already uses. No marketing fluff.
• Use straight quotes (' and "), not curly quotes.
• Do not invent PRs, authors, or commit messages in "What's Changed". That section must be sourced from the GitHub API, not synthesized.
• Never run gh release create (or any other command that writes to GitHub) until the user has seen the fully assembled draft (opener, Big Updates, Improvements, Upgrade Notes, What's Changed, Full Changelog line — the whole document, not just the feature list from step 5) and explicitly approved it. Step 5's feature-list confirmation is necessary but not sufficient; the user must sign off on the actual prose before anything is pushed to GitHub.

Procedure

1. Confirm version, diff baseline, and style reference

# Diff baseline: latest non-pre-release tag (minor OR patch):
git tag --sort=-v:refname | grep -v -- '-' | head -1
# Style reference: latest published minor (vX.Y.0, no pre-releases):
git tag --list 'v*.*.0' --sort=-v:refname | grep -v -- '-' | head -1
# Recent tags to suggest the target version:
git tag --sort=-creatordate | head -10

Confirm the target version, diff baseline, and style reference with the user before proceeding. The diff baseline and style reference often differ — e.g. baseline v0.21.3, style v0.21.0. Use the baseline for everything that touches commit range, and the style reference for tone/structure.

2. Read the style reference's notes for tone and structure

gh release view <STYLE_REF> --repo obot-platform/obot

Match its structure exactly:

1. One-paragraph opener: We're excited to announce the <VERSION> release of the Obot MCP Platform. This release <one-sentence theme summary>.
2. ## Big Updates with 3-6 ### Feature Name subsections. Each subsection is 1-3 short paragraphs in plain prose. Link to docs with [docs](https://docs.obot.ai/...) when a docs page exists.
3. Optional ## Improvements section with a short bulleted list of smaller usability/perf items. Include only if there are clearly several smaller user-facing improvements worth calling out. Omit otherwise (v0.21.0 has no Improvements section).
4. ## Upgrade Notes — usually There are no major breaking changes in this release. If the diff contains breaking changes (removed APIs, renamed config, schema migrations, removed env vars), call them out explicitly and concretely. Check commits with chore: remove, BREAKING, or schema/migration changes.
5. ## What's Changed — generated via API (see step 7).
6. Trailing **Full Changelog**: https://github.com/obot-platform/obot/compare/<DIFF_BASELINE>...<VERSION>.

3. Survey the commit range

git log <DIFF_BASELINE>..HEAD --oneline
git log <DIFF_BASELINE>..HEAD --format='%H%n%s%n%b%n---'  # full bodies if more context needed

Identify candidate big features. Heuristics:

• feat: commits are top candidates.
• enhance: commits that introduce notable user-visible capability also qualify.
• Group related commits into one theme (e.g. several image pull secrets commits become one "Image Pull Secrets" feature).
• fix:, chore:, docs:, dependabot, and CI commits are NOT big features.

Aim for 3-6 Big Updates. If the range is small, fewer is fine. If many candidates exist, prioritize features that change what users can do, not internal refactors.

Deep-read each candidate before drafting its gist. Commit subjects are too thin to build a release note on. For every candidate Big Update (and every PR that gets merged into one as part of a theme), do all of:

# Full PR body + comments + reviewers:
gh pr view <NUM> --repo obot-platform/obot --comments

# Files changed (helps confirm scope and spot user-facing surface area):
gh pr view <NUM> --repo obot-platform/obot --json files --jq '.files[].path'

Finding linked issues. This repo deliberately does NOT use GitHub's closes #N / fixes #N keywords, so the closingIssuesReferences field will almost always be empty. Issues are referenced in PR body or comments as plain text. Grep the PR body and the comment thread (both come back from gh pr view --comments) for:

• bare #<number> references
• obot-platform/obot#<number>
• full URLs like https://github.com/obot-platform/obot/issues/<number>
• "issue 1234", "see 1234", or similar prose mentions of a 3-5 digit number near words like "issue", "tracked in", "addresses", "from"

For every issue number found that way, read it:

gh issue view <ISSUE_NUM> --repo obot-platform/obot --comments

Be slightly generous — false positives (numbers that turn out to be PR numbers, version numbers, or unrelated) are cheap to read and discard. Missing the issue that explains the why is what you're avoiding. Linked issues usually contain the user problem, the design discussion, and the constraints that the PR body and commit message omit. That context is what makes the difference between a release note that says "added X" and one that explains what X actually unlocks for users.

If a candidate is a theme spanning multiple PRs, deep-read the largest one (or two) — not every single follow-up fix PR. Use judgement: enough reading to write an accurate gist, not exhaustive.

Do not write up a feature whose PR(s) and linked issues you have not actually read in this session.

4. Check the milestone for release-note issues

The team flags items that need an explicit callout in the release (deprecations, upgrade warnings, behavior changes, required config changes) by labeling GitHub issues with release-note and attaching them to the milestone matching the release.

Look them up:

# Try the version both with and without the leading "v" — milestones are usually "v0.22.0" but check both.
gh issue list --repo obot-platform/obot --milestone "<VERSION>" --label "release-note" --state all \
  --json number,title,body,url,state,labels --limit 50
gh issue list --repo obot-platform/obot --milestone "<VERSION_NO_V>" --label "release-note" --state all \
  --json number,title,body,url,state,labels --limit 50

If neither returns results, also check whether the milestone exists at all:

gh api repos/obot-platform/obot/milestones --jq '.[] | {title, number, state}'

If the milestone is missing or has no release-note issues, note that to the user and continue without callouts. Do not invent callouts.

For each issue found, draft a concise note:

• One or two sentences max. State the deprecation, warning, or required action plainly.
• Link to the issue at the end: See [#<NUMBER>](<URL>) for details.
• Classify each as either:
  • Upgrade Notes item (default): goes into the ## Upgrade Notes section as a bullet or short paragraph. Use for deprecations, removed config, required migrations, behavior changes that affect all users.
  • Feature-attached callout: render as a blockquote inside the relevant ### Feature subsection in Big Updates. Use only when the note is specifically about how to enable, configure, or be aware of one of the features being highlighted. Mirror the blockquote style from v0.19.0's Message Policies entry.

Do not paste the issue body verbatim. Distill it. The issue is for details; the release note is the headline.

5. Confirm the feature list and release-note callouts with the user (required, do not skip)

Before writing any prose, present the candidate Big Updates AND the release-note callouts back to the user for review. This catches three failure modes: highlighting the wrong things, mis-describing what a feature actually does, and misclassifying a release-note callout. Format the review like this:

Candidate Big Updates for <VERSION> (range <DIFF_BASELINE>..HEAD):

1. <Proposed feature title>
   Gist: <one or two sentences summarizing what this feature is and why it matters>
   Source PRs: #6567, #6605, #6636, ...

2. <Proposed feature title>
   Gist: ...
   Source PRs: ...

Also considered but dropped (say if any should be promoted):
- <feature> — reason dropped (e.g. "internal refactor only", "rolled into #N", "fix not feat")

Release-note callouts found in milestone <VERSION>:

1. [#<NUM>] <issue title>
   Proposed note: <drafted one or two sentences>
   Classified as: Upgrade Notes  (or: Feature-attached callout under "<Feature Title>")

(If none: "No release-note issues found in milestone <VERSION>.")

Questions for you:
a. Are these the right features to highlight? Any to add, drop, or merge?
b. For each kept feature, is the gist accurate? Reply with corrections inline or just "all good".
c. Any feature here that should be downgraded to the Improvements bullet list instead?
d. For each release-note callout: is the wording accurate, and is it classified in the right place (Upgrade Notes vs. attached to a feature)?

Use AskUserQuestion when there are concrete forks (e.g. multiple ways to title or scope a feature, or whether a callout belongs in Upgrade Notes vs. on a feature). For open-ended gist corrections, plain text reply is fine. Wait for the user's response and incorporate corrections before proceeding to step 6. Do not draft prose for a feature or callout whose wording the user has not confirmed or corrected.

If the user corrects a gist or callout, mirror their wording closely in the draft. They know the feature better than the commit messages or issue body do.