---
name: maintain-changelog
description: Use when the user says "update the CHANGELOG" / "changelog from PRs since {version}" / "draft the changelog entries" — fetches merged PRs + linked issues since the given version tag via the connected code host, filters for user-facing changes, groups them Keep-A-Changelog style (Added / Changed / Deprecated / Removed / Fixed / Security), and writes a DRAFT snippet to `changelog/{version}.md`. Hard no: never auto-commits the canonical CHANGELOG.md — user copies the snippet in themselves.
---

# Maintain Changelog

## When to use

- User: "update the CHANGELOG from merged PRs since {version}" /
  "draft changelog entries for {version}" / "what's new since
  {version-tag}".
- Implicit trigger: the user mentions a version bump and references
  the last tagged release.

## Steps

1. **Read engineering context.** Open
   `../head-of-engineering/engineering-context.md`. If missing or
   empty, stop and tell the user:
   > "I need the engineering context doc to judge what's user-facing.
   > Run the Head of Engineering's `define-engineering-context`
   > first."

2. **Read config.** `config/changelog-format.md` (style reference —
   if it's an existing CHANGELOG.md, mirror its headings and tone).
   If missing or "none", default to Keep-A-Changelog
   (keepachangelog.com) with these headings: `Added`, `Changed`,
   `Deprecated`, `Removed`, `Fixed`, `Security`.

3. **Resolve inputs.**
   - Version source: the git tag the user named (e.g. `v1.4.0`).
   - Version target: what the user is about to ship (e.g. `v1.5.0`
     or `Unreleased`). If unstated, ask ONE question:
     > "What's the next version? (e.g. `v1.5.0`, or just
     > `Unreleased` for now.) I'll put the draft under that heading."
   - Repo: resolve via `config/repo.json`; if missing, ask OR run
     `composio search code-hosting` for a connected host and list
     accessible repos.

4. **Fetch merged PRs since the tag.** Run `composio search
   code-hosting` to find the GitHub (or GitLab / Bitbucket / Gitea)
   tool. Fetch merged PRs whose merge commit is after the tag, with:
   - Title
   - Body (first 500 chars — scan for "Closes #N" linked issues)
   - Author
   - Number
   - Labels
   - Merge date
   - Linked issue titles (fetch the issues that are referenced
     in-body with `Closes #` / `Fixes #` / `Resolves #`).

   If no connected code host, tell the user which category to link
   and stop.

5. **Filter for user-facing changes.**
   - **Include:** new features, behavior changes, bug fixes that
     affect user-visible output, security fixes, breaking changes,
     deprecations, new configuration options.
   - **Skip:** internal refactors with no user effect, CI-only
     changes, dependency bumps (unless they change behavior), tests
     only, docs-only (unless major), formatting / lint only.
   - Heuristic: if the PR title starts with `refactor:`, `chore:`,
     `test:`, `ci:`, skip by default — but **scan the body** for
     "user-facing" mentions and include if in doubt. Err toward
     including; the user will cut.

6. **Classify each kept PR** under Keep-A-Changelog headings:
   - `Added` — new features, new endpoints, new config options.
   - `Changed` — behavior changes to existing features (non-
     breaking).
   - `Deprecated` — features scheduled for removal.
   - `Removed` — features now gone (breaking).
   - `Fixed` — bug fixes.
   - `Security` — vulnerability fixes / auth changes.

7. **Rewrite each PR title** into user-facing language:
   - **From the user's perspective.** "Fixed race condition in
     widget saves" > "Refactor widget save mutex".
   - **Active voice, one line.** Lead with the verb (Add / Change /
     Fix / Remove).
   - **Link back** with `(#{PR-number})` at the end — links go in a
     footer section the user can strip if they don't want PR
     references.
   - **Breaking changes** prefixed with `**BREAKING:**` — this is
     critical, never omit.

8. **Compose the draft snippet.** Exact structure (the user will
   paste this under the target version in their canonical CHANGELOG.md):

   ```markdown
   ## [{target-version}] — {YYYY-MM-DD}

   ### Added
   - Add `/v1/widgets/batch` endpoint for bulk creation. (#142)
   - Add `WIDGET_RATE_LIMIT` env var to cap API writes. (#148)

   ### Changed
   - **BREAKING:** Rename `widget.price` to `widget.price_cents`.
     Clients on < v1.4 must migrate. (#151)
   - Log format is now JSON by default (was plaintext). Set
     `LOG_FORMAT=text` to revert. (#155)

   ### Fixed
   - Fix race condition when two clients save the same widget
     concurrently. (#144)
   - Fix silent failure when `price_cents` was negative (now
     returns 400). (#147)

   ### Security
   - Rotate JWT signing key on startup if `JWT_SECRET` is the
     default dev value. (#160)

   ---

   ### PR references
   - (#142) [Title] — @author, YYYY-MM-DD
   - (#144) [Title] — @author, YYYY-MM-DD
   - ...
   ```

9. **Write** to `changelog/{version}.md` atomically (`*.tmp` →
   rename). Where `{version}` is the target version slug (e.g.
   `v1.5.0.md` or `unreleased.md`).

10. **Append to `outputs.json`** (`type: "changelog"`,
    `title: "Changelog draft — {target-version}"`,
    `summary: "{N} entries: {added} added, {changed} changed,
    {fixed} fixed, {security} security. {M} PRs considered, {K}
    skipped as non-user-facing."`,
    `path: "changelog/{version}.md"`, `status: "draft"`, timestamps).

11. **Summarize to user** — one paragraph: counts per Keep-A-
    Changelog heading, the top 1-2 breaking changes to call out, any
    PRs where you were unsure (ask the user to confirm), and the
    path. End with: **"This is a draft snippet. Copy the block above
    into your canonical CHANGELOG.md at the repo root, review, and
    commit. I never auto-commit the CHANGELOG."**

## Hard nos

- **Never auto-commit the canonical CHANGELOG.md** — this is the
  load-bearing hard no for this skill. Output is a draft snippet at
  `changelog/{version}.md` only; the user pastes into
  `CHANGELOG.md` at their repo root and commits.
- Never invent PRs / issues — every entry cites a real PR number.
- Never omit `**BREAKING:**` prefix on breaking changes.
- Never write without reading `engineering-context.md` first.

## Outputs

- `changelog/{version}.md` — draft snippet for ONE release.
- Appends to `outputs.json` with `{ id, type: "changelog", title,
  summary, path, status: "draft", createdAt, updatedAt }`.