---
name: fzyzcjy/frb-write-changelog
source: https://app.decimal.ai/s/fzyzcjy-frb-write-changelog@1/SKILL.md
source_sha256: 881fdb071370
---

# FRB Write Changelog

## Step 1: Inspect `CHANGELOG.md`

Read the top of `CHANGELOG.md`.

- Confirm the target version section exists, or add it.
- Keep the existing V2 "what's new" header line.
- Inspect `git diff -- CHANGELOG.md` before editing.
- Replace only the target section if it already contains a placeholder such as `* TODO`.

## Step 2: Identify the previous release tag

Find the latest release tag before the target version.

```bash
git tag --sort=-creatordate | head -n 20
```

Use that tag as the lower bound for the new changelog entry.

## Step 3: Collect merged PRs

Use GitHub CLI to collect merged PRs after the previous version.

```bash
gh pr list --state merged --limit 200 --json number,title,author,mergedAt,baseRefName,url
gh pr view <number> --json number,title,author,url
```

Use the previous version as the lower bound when deciding which merged PRs belong to the target release.

## Step 4: Filter and normalize

Keep all PRs in merged status that belong to the release range.

- Exclude unmerged PRs.
- Exclude PRs outside the release range.
- When refreshing an already-published release, use both the previous release timestamp and the target release tag timestamp so later post-release PRs are not pulled into the published section.
- Do not filter by target branch.
- Keep docs, CI, and chore PRs if they are merged in the range.
- Exclude only all-contributors PRs such as `docs: add <name> as a contributor for code/doc`; do not exclude ordinary documentation PRs whose titles start with `docs: add`.

Normalize titles before writing.

- Rewrite noisy internal titles into concise changelog language.
- Avoid duplicate summaries for split or "continued" PRs.
- Preserve repo-specific capitalization such as `CI`, `GitHub`, `Flutter`, `Rust`, `DCO`, and `V1`.

## Step 5: Write the section

Match the existing changelog style.

- Write each item as `* Summary #1234`.
- Append `(thanks @username)` for every third-party human-authored PR in the release range, including docs, CI, chore, tooling, and feature PRs.
- When a changelog entry combines local maintainer PRs with a third-party PR, append the third-party thanks to that combined entry.
- If multiple third-party authors appear in one combined entry, include each author in the same entry.
- Place entries with `(thanks @username)` before entries without thanks.
- Within the thanks group and the no-thanks group, keep items in merge order from newest to oldest unless the surrounding section clearly uses another order.

Edit only `CHANGELOG.md`. Do not manually edit generated files for this task.

## Step 6: Review and commit

Review the final diff.

- Confirm the change is limited to the target release section.
- Confirm wording and ordering match nearby release sections.
- Create a small atomic commit after finishing the edit.

## Step 7: Run mechanical verification

Run the changelog verifier after finishing the draft.

```bash
gh pr list --state merged --limit 200 --json number,title,author,mergedAt,baseRefName,url > /tmp/frb-merged-prs.json
uv run --script .claude/skills/frb-write-changelog/verify_changelog.py \
  --version <VERSION> \
  --previous-release-time <PREVIOUS_RELEASE_TIMESTAMP> \
  --release-time <TARGET_RELEASE_TIMESTAMP> \
  --merged-prs-json /tmp/frb-merged-prs.json
```

The verifier checks that:

- PR numbers in the target section are complete, not duplicated, and not unexpected.
- Third-party thanks authors are complete and not unexpected, including ordinary documentation PR authors. The same author may be thanked on multiple entries.
- Entries with third-party thanks appear before entries without thanks.
- `docs: add <name> as a contributor ...` all-contributors PRs are ignored.

Use `--ignore-pr <NUMBER>` only for a documented intentional exclusion. Use `--extra-local-pr <NUMBER>` for a stacked local maintainer PR that belongs in the changelog but is not present in the merged PR JSON yet. Use `--extra-thanks-author <LOGIN>` only for a verified co-author or contributor credited by a release-range PR even though their source PR falls outside the release range; record the source PR and reason in the release journal.

Apply any confirmed fixes, then re-run the verifier.

## Step 8: Ask the user to review ordering

Tell the user the changelog draft is complete and ask for a manual review.

- Ask the user to review the wording.
- Ask the user to review the ordering of entries.
- Adjust the ordering if the user wants a different presentation from the mechanically collected order.

## Step 9: Re-verify after human edits

Run the mechanical verifier again after the user finishes manual edits.

- Confirm there are no missing, duplicated, or extra PR numbers.
- Confirm there are no missing or unexpected third-party thanks authors.
- Confirm entries with third-party thanks appear before entries without thanks.
- Apply any confirmed fixes, then do one final diff check.

If the user explicitly wants an independent review, ask a separate reviewer or subagent to compare the final `CHANGELOG.md` against the same merged PR list.