Port update-changelog improvements from react_on_rails

[justin808]

Summary

Syncs recent improvements from shakacode/react_on_rails (PRs #2596, #2608, #2628) into the /update-changelog command.

Changes to .claude/commands/update-changelog.md:

• Explicit version argument: /update-changelog 9.7.0.rc.10 now stamps the exact version provided, skipping auto-computation
• Git-tags-only RC index: RC/beta index computation now uses only git tags, not changelog headers (headers are drafts, tags are shipped versions)
• Ambiguous bump explanation: Version confirmation step now explains reasoning when bump type is ambiguous and asks user to confirm/override
• Tag reconciliation step: New Step 2 catches missing version sections by comparing git tags against changelog headers (the Update webpack-dev-server #1 source of errors when skipped)
• Auto-commit/push/PR: When stamping versions (release/rc/beta/explicit), automatically creates branch, commits, pushes, and opens PR
• Heading consolidation: Prerelease collapse now consolidates duplicate category headings (e.g., two ### Fixed become one)
• Orphaned link cleanup: Prerelease collapse removes leftover compare links for collapsed prerelease sections
• v prefix clarity: Explicit note that compare links must use v prefix to match git tags
• Header placement rule: New version header must go immediately after ## [Unreleased]

No changes to rakelib/release.rake or docs/releasing.md — react_on_rails had no changes to those files in the last 3 days.

Test plan

• Run /update-changelog and verify the new tag reconciliation step (Step 2) runs before adding entries
• Run /update-changelog rc and verify RC index is computed from git tags only
• Run /update-changelog 9.7.0 and verify explicit version stamps correctly
• Run /update-changelog release and verify it auto-commits, pushes, and opens PR

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk because this PR only updates the .claude/commands/update-changelog.md documentation/workflow guidance and does not change runtime code paths.

Overview
Updates the /update-changelog command guide to support explicit version stamping and to clarify that RC/beta increments must be derived only from git tags (not draft changelog headers), with improved user confirmation when version bump type is ambiguous.

Reworks the process steps to add an upfront tag-vs-changelog reconciliation phase for missing release sections, clarifies compare-link v-prefix requirements and header placement, and expands prerelease-collapsing rules (merge duplicate category headings, remove orphaned diff links). When stamping versions (release/rc/beta/explicit), the guide now instructs auto-creating a branch, committing, pushing, and opening a PR.

^{Written by Cursor Bugbot for commit b116cc2. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added explicit-version option and validation requiring it to be newer than existing tags.
  • Updated 5-step workflow with a reconciliation step that creates/moves version sections and consolidates prereleases.
  • Enforced v-prefix for bottom compare links and expanded formatting/verification guidance, plus CRITICAL insertion position note.
• New Features
  • Shows computed version with confirmation prompt, explains ambiguous bumps, and summarizes actions taken.
  • Optional auto-commit/PR creation limited to CHANGELOG.md.

[coderabbitai]

Warning

Rate limit exceeded

@justin808 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 14 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2badcd19-7f82-46c9-a6b8-067c774c6774

📥 Commits

Reviewing files that changed from the base of the PR and between 9b61683 and da32b05.

📒 Files selected for processing (1)

• .claude/commands/update-changelog.md

Walkthrough

Adds an explicit-version option to update-changelog, changes RC/tag determination to rely on git tags, adds a tag↔changelog reconciliation step, restructures the workflow into Steps 1–5 with confirmation and stamping paths, and adds optional auto-commit/PR creation plus stricter bottom-link and formatting rules.

Changes

Cohort / File(s)

Summary

Documentation /.claude/commands/update-changelog.md

Introduces --version/explicit-version path, changes RC/version indexing to use git tags only, adds reconciliation of tags with CHANGELOG (create/move/collapse sections, remove orphaned diff links), enforces v-prefixed bottom compare links and header placement, reworks workflow into Steps 1–5 (incl. confirmation and ambiguous-bump messaging), and adds optional auto-commit/PR behavior and expanded formatting/validation guidance.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibbled lines and stitched the flow,
I stamped new versions in neat rows,
Tags and changelogs cuddled tight,
Steps aligned beneath the light,
A rabbit cheers — the docs now glow! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: porting update-changelog improvements from react_on_rails, which aligns with the PR's primary objective of syncing recent improvements from shakacode/react_on_rails.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jg/sync-ror-release-changes

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

The example uses RubyGems dot-format (9.7.0.rc.10) while the rest of the document consistently uses npm semver dash-format (v9.6.0-rc.1). The document explicitly warns against using dot format in changelog headers (line ~147: "Wrong: ## [v9.6.0.rc.1] (RubyGems format — do NOT use this in CHANGELOG.md headers)").

This is confusing. The description also only mentions .rc.N / .beta.N suffixes, not the dash variants.

Suggest clarifying which format(s) are accepted and showing conversion behaviour:

Suggested change

- **Explicit version** (`/update-changelog 9.7.0.rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must look like a semver version (with optional `.rc.N` or `.beta.N` suffix).

- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing.

[claude]

The command here is missing the -l 'v*' filter used everywhere else in the document. Without it, non-version tags (e.g. CI tags, tooling tags) could appear in the results and be mistakenly treated as the latest version.

Suggested change

	1. Get the latest git tag: `git tag --sort=-v:refname | head -5`
	1. Get the latest git tag: `git tag -l 'v*' --sort=-v:refname | head -5`

[claude]

The auto-commit step doesn't address the case where there are other uncommitted or staged changes in the working tree. Committing only CHANGELOG.md is safe with git add CHANGELOG.md, but the instruction should be explicit about this to prevent accidentally staging unrelated edits.

Suggested change

	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	- Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
	- Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit
	- Push and open a PR with the changelog diff as the body
	- If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
	- Remind the user to run `bundle exec rake create_release` (no args) after merge to publish and auto-create the GitHub release

[claude]

Review: Port update-changelog improvements from react_on_rails

Overall this is a solid improvement — the structured steps, tag reconciliation, and heading-consolidation rules all address real pain points. Three issues worth fixing before merge:

1. Version format inconsistency in the explicit-version example (line 13)

The new explicit-version argument is shown as /update-changelog 9.7.0.rc.10 (RubyGems dot-format), but everything else in the document uses npm semver dash-format (v9.6.0-rc.1). The document even explicitly marks dot-format as wrong for changelog headers. The description also only mentions .rc.N / .beta.N suffixes, omitting the dash variants.

This could cause the AI to accept a dot-format string, insert it verbatim as a changelog header, and produce an entry the release rake tasks can't parse. See inline comment on line 13.

2. Missing -l 'v*' filter in Step 2 git tag command (line 203)

The Step 2 reconciliation command is git tag --sort=-v:refname | head -5, but every other git tag call in the document includes -l 'v*' to filter out non-version tags. Without the filter, tooling or CI tags could be treated as the latest release and silently break the reconciliation comparison. See inline comment on line 203.

3. Auto-commit step doesn't guard against staging unrelated changes (line 268)

Step 5's auto-commit instruction doesn't specify that only CHANGELOG.md should be staged. If there are other uncommitted edits in the working tree (common during a release prep session), a plain git add . or git commit -a would pull them in. The instruction should explicitly stage only CHANGELOG.md and warn + stop if other dirty files exist. See inline comment on line 268.

---

No runtime code is changed, so the risk is low, but issues 1 and 2 in particular could cause silent correctness bugs when the command is actually run.

[greptile-apps]

Greptile Summary

Ports several improvements to the /update-changelog Claude command from react_on_rails, including: explicit version argument support, git-tags-only RC index computation, a new tag reconciliation step (Step 2), auto-commit/push/PR workflow for version stamping, heading consolidation during prerelease collapse, orphaned link cleanup, and clarified v prefix requirements for compare links. The process section is refactored from a flat numbered list into clearly labeled sequential steps (Steps 1-5).

• Format ambiguity in explicit version example: The new explicit version example (9.7.0.rc.10) uses RubyGems dot format, but the document's own rules (lines 144-147) mandate npm semver dash format (v9.7.0-rc.10) for changelog headers. This could lead to incorrect header formatting when an explicit version is provided.
• The restructured step-based process (Steps 1-5) is a clear improvement over the previous flat list, making it harder to miss the critical tag reconciliation step.
• Auto-commit/push/PR behavior in Step 5 is well-designed with appropriate fallback guidance if push/PR creation fails.

Confidence Score: 4/5

• This PR is safe to merge — it only changes a Claude command template with no runtime code impact, though one documentation inconsistency should ideally be fixed.
• Single file change to a Claude command template (no production code). The improvements are well-structured and clearly ported from a sibling project. One format inconsistency in the explicit version example could cause incorrect behavior when the command is invoked, but it's easily fixable.
• update-changelog.md line 13: explicit version format example conflicts with the document's own npm semver format requirements.

Important Files Changed

Filename	Overview
.claude/commands/update-changelog.md	Significant improvements to the changelog update command (tag reconciliation, auto-commit/PR, heading consolidation, orphaned link cleanup). One format ambiguity issue found: the explicit version example uses RubyGems dot format while the document mandates npm semver dash format for headers.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["/update-changelog ARGS"] --> B{Parse argument}
    B -->|No argument| C["Step 1: Fetch & read state"]
    B -->|release / rc / beta| C
    B -->|Explicit version| C

    C --> D["Step 2: Reconcile tags with changelog\n(compare git tags vs changelog headers)"]
    D --> E{"Missing tagged versions?"}
    E -->|Yes| F["Create missing version sections\nMove entries from Unreleased"]
    E -->|No| G["Step 3: Add new entries\nfor post-tag commits"]
    F --> G

    G --> H{Version mode given?}
    H -->|No| I["Step 5: Verify & finalize\nRun linting, show summary"]
    H -->|Yes| J["Step 4: Stamp version header"]
    J --> K{"rc or beta?"}
    K -->|Yes| L["Collapse prior prereleases\nConsolidate headings\nRemove orphaned links"]
    K -->|No| M["Insert version header\nafter Unreleased"]
    L --> M
    M --> I

    I --> N{Version was stamped?}
    N -->|Yes| O["Auto-commit, push,\nand open PR"]
    N -->|No| P["Done — entries in Unreleased"]
    O --> Q["Remind user to run\nbundle exec rake create_release"]

Loading

_{Last reviewed commit: b116cc2}

[greptile-apps]

Explicit version example uses wrong format

The example /update-changelog 9.7.0.rc.10 uses RubyGems dot format (.rc.), and the description says "optional .rc.N or .beta.N suffix". However, lines 144-147 of this same document explicitly state:

Use npm semver format with dashes, NOT RubyGems dot format

• Correct: ## [v9.6.0-rc.1]
• Wrong: ## [v9.6.0.rc.1]

This creates an ambiguity: if the user passes 9.7.0.rc.10, should the command stamp ## [v9.7.0-rc.10] (npm semver, matching the rest of the doc) or ## [v9.7.0.rc.10] (RubyGems, matching the example)? There's no instruction to convert between formats.

Consider either:

1. Changing the example to use dash format: /update-changelog 9.7.0-rc.10, or
2. Adding an explicit note that the command accepts either format and normalizes to npm semver dashes for the changelog header.

Suggested change

- **Explicit version** (`/update-changelog 9.7.0.rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must look like a semver version (with optional `.rc.N` or `.beta.N` suffix).

- **Explicit version** (`/update-changelog 9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must look like a semver version (with optional `-rc.N` or `-beta.N` suffix). If passed in RubyGems dot format (e.g., `9.7.0.rc.10`), convert to npm semver dash format (`v9.7.0-rc.10`) for the changelog header.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b116cc267e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use npm prerelease format for explicit version input

The new explicit-version guidance uses dot-form prereleases (9.7.0.rc.10) and says to stamp the exact provided value, which conflicts with the existing header rule in this same command doc that changelog versions must use npm-style dashes (e.g., v9.6.0-rc.1). In explicit RC/beta runs, this can generate a changelog header/link that does not match git tag names, so later reconciliation/release steps cannot align the section with the actual tag.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Filter latest-tag lookup to version tags

Step 2 now uses git tag --sort=-v:refname | head -5 without a version pattern, so a non-release tag can be treated as the "latest tag" for reconciliation. In repositories that carry auxiliary tags, this produces false missing-version detection and incorrect commit ranges for moved/added changelog entries; limiting the list to version tags (as the previous -l 'v*' flow did) avoids that failure mode.

Useful? React with 👍 / 👎.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.claude/commands/update-changelog.md (2)

13-13: Clarify explicit-version normalization to header/tag format.

Explicit input is shown in RubyGems prerelease form (9.7.0.rc.10), while headers/links must use git-tag form (v9.7.0-rc.10). Add one explicit normalization rule to avoid invalid stamped headers.

Suggested wording

-- **Explicit version** (`/update-changelog 9.7.0.rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must look like a semver version (with optional `.rc.N` or `.beta.N` suffix).
+- **Explicit version** (`/update-changelog 9.7.0.rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version.
+  - Accept `X.Y.Z`, `X.Y.Z.rc.N`, or `X.Y.Z.beta.N` as input.
+  - Always normalize stamped CHANGELOG headers and compare links to git-tag format: `## [vX.Y.Z]`, `## [vX.Y.Z-rc.N]`, `## [vX.Y.Z-beta.N]`.

Also applies to: 146-153

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 13, Update the explicit-version
documentation for the /update-changelog command to state that RubyGems-style
prerelease input like "9.7.0.rc.10" will be normalized to git-tag/header form
"v9.7.0-rc.10" when stamping headers/links; add a short normalization rule
sentence and an explicit example showing the input and the normalized header/tag
output, and mirror the same clarification for the other occurrence referenced
(lines 146–153).

---

219-219: Return tag date in release-header format to reduce manual mistakes.

The command currently outputs YYYY-MM-DD, but release headers require Month Day, Year.

Suggested fix

-5. Get the tag date with: `git log -1 --format="%Y-%m-%d" TAG_NAME`
+5. Get the tag date in header format with: `git log -1 --date=format:"%B %-d, %Y" --format="%ad" TAG_NAME`

Also applies to: 142-143

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 219, The script currently uses
git log -1 --format="%Y-%m-%d" TAG_NAME which outputs YYYY-MM-DD; replace it
with git log -1 --date=format:"%B %e, %Y" --format="%ad" TAG_NAME so the tag
date is emitted as "Month Day, Year" (e.g., March 3, 2024); update both
occurrences referenced (the current line and the ones around lines 142-143)
where the format string "%Y-%m-%d" appears.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/commands/update-changelog.md:
- Line 203: The command `git tag --sort=-v:refname | head -5` can return
non-release tags; update the instruction to only list tags that start with "v"
by filtering tag names (e.g., use git tag --list 'v*' --sort=-v:refname | head
-5) so reconciliation considers release tags only; edit the line containing the
git command in update-changelog.md to use the 'v*' filter.

---

Nitpick comments:
In @.claude/commands/update-changelog.md:
- Line 13: Update the explicit-version documentation for the /update-changelog
command to state that RubyGems-style prerelease input like "9.7.0.rc.10" will be
normalized to git-tag/header form "v9.7.0-rc.10" when stamping headers/links;
add a short normalization rule sentence and an explicit example showing the
input and the normalized header/tag output, and mirror the same clarification
for the other occurrence referenced (lines 146–153).
- Line 219: The script currently uses git log -1 --format="%Y-%m-%d" TAG_NAME
which outputs YYYY-MM-DD; replace it with git log -1 --date=format:"%B %e, %Y"
--format="%ad" TAG_NAME so the tag date is emitted as "Month Day, Year" (e.g.,
March 3, 2024); update both occurrences referenced (the current line and the
ones around lines 142-143) where the format string "%Y-%m-%d" appears.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2c47fcbd-f457-4860-a781-9442fe928965

📥 Commits

Reviewing files that changed from the base of the PR and between b259a0e and b116cc2.

📒 Files selected for processing (1)

• .claude/commands/update-changelog.md

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Tag reconciliation command missing version tag filter
  • Updated the Step 2 tag reconciliation command to use git tag -l 'v*' --sort=-v:refname | head -5 so only version tags are compared against changelog headers.

Or push these changes by commenting:

@cursor push 40dfcdafc0

Preview (40dfcdafc0)

diff --git a/.claude/commands/update-changelog.md b/.claude/commands/update-changelog.md
--- a/.claude/commands/update-changelog.md
+++ b/.claude/commands/update-changelog.md
@@ -200,7 +200,7 @@
 
 **This step catches missing version sections and is the #1 source of errors when skipped.**
 
-1. Get the latest git tag: `git tag --sort=-v:refname | head -5`
+1. Get the latest git tag: `git tag -l 'v*' --sort=-v:refname | head -5`
 2. Get the most recent version header in CHANGELOG.md (the first `## [vVERSION]` after `## [Unreleased]`)
 3. **Compare them.** If the latest git tag does NOT match the latest changelog version header, there are tagged releases missing from the changelog. For example:
    - Latest tag: `v9.6.0-rc.4`

[cursor]

Tag reconciliation command missing version tag filter

Medium Severity

The git command in the tag reconciliation step (git tag --sort=-v:refname | head -5) is missing the -l 'v*' filter that all other tag-listing commands in this file use (lines 51 and 282). Without this filter, the command could return non-version tags (e.g., annotation tags, deployment markers), causing false mismatches when comparing against changelog headers.

 

[claude]

The restructured 5-step workflow is a clear improvement. The explicit tag reconciliation step (Step 2) addresses a real failure mode, and the auto-commit/push/PR automation removes error-prone manual steps. A few issues to address below in inline comments.

[claude]

The RubyGems dot-format conversion only mentions the RC suffix (9.7.0.rc.10 → 9.7.0-rc.10), but the same conversion applies to beta. Consider making the rule explicit for both:

Suggested change

- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10`), convert to npm semver dash format (`v9.7.0-rc.10`) for the changelog header.

- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10` or `9.7.0.beta.2`), convert to npm semver dash format (`v9.7.0-rc.10` or `v9.7.0-beta.2`) for the changelog header.

[claude]

After Step 2 may have reconciled several missing tags, LATEST_TAG here is ambiguous — a model following this literally might pick an older reference from before reconciliation. Suggest making it explicit:

Suggested change

	#### Step 3: Add new entries for post-tag commits
	1. Run `git log --oneline LATEST_TAG..origin/main` to find commits after the latest tag (LATEST_TAG is the most recent git tag, i.e., the same one identified in Step 2)

[claude]

The safety check only guards against uncommitted changes, but not against the current branch being something other than main. If a user already has a half-completed changelog branch checked out, the command would create a new branch from that diverged state, leading to a confusing history.

Suggest adding a branch guard before creating the feature branch:

Suggested change

	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	- Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
	- Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit
	- Push and open a PR with the changelog diff as the body
	- If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
	- Remind the user to run `bundle exec rake create_release` (no args) after merge to publish and auto-create the GitHub release
	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	- Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
	- Verify the current branch is `main` (`git branch --show-current`); if not, warn the user and stop
	- Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit
	- Push and open a PR with the changelog diff as the body
	- If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
	- Remind the user to run `bundle exec rake create_release` (no args) after merge to publish and auto-create the GitHub release

[claude]

This placement rule is already stated in Step 4 (line 239: "Insert the version header immediately after ## [Unreleased]"). Repeating it here as CRITICAL adds noise. Consider replacing with a cross-reference:

Suggested change

	**CRITICAL**: The new version header must be inserted **immediately after `## [Unreleased]`**, NOT after any descriptive text. This ensures correct ordering of version headers.
	**Note**: The new version header must be inserted **immediately after `## [Unreleased]`** (see Step 4). This ensures correct ordering of version headers.

[coderabbitai]

🧹 Nitpick comments (4)

.claude/commands/update-changelog.md (4)

64-64: Clarify wording for explicit version path.

The instruction mentions "computed version" but when an explicit version is provided (line 13), there's no computation. Consider: "Check that the computed or provided version is newer than ALL existing tags."

📝 Suggested clarification

-4. **Verify**: Check that the computed version is newer than ALL existing tags (stable and prerelease). If not, ask the user what to do.
+4. **Verify**: Check that the computed or provided version is newer than ALL existing tags (stable and prerelease). If not, ask the user what to do.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 64, Update the sentence that
currently reads "Check that the computed version is newer than ALL existing tags
(stable and prerelease)." to explicitly cover the explicit-version path by
changing it to "Check that the computed or provided version is newer than ALL
existing tags (stable and prerelease)." — edit the line near the existing
reference to the explicit-version option (mentioned at line 13) in
update-changelog.md so the wording covers both computed and user-provided
versions.

---

224-224: PR extraction pattern assumes standard GitHub format.

The pattern grep -oE "#[0-9]+" works for standard GitHub commit messages but might miss PRs referenced in other formats. This is likely acceptable for the standard workflow, but consider documenting this assumption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 224, The PR extraction step
uses the grep pattern `grep -oE "#[0-9]+"`, which only matches GitHub-style
“#123” references; update the documentation near the `2. **Extract ALL PR
numbers**` line to state this assumption and either (a) add examples of other
common reference formats to be aware of or (b) provide an alternative extraction
command (e.g., also matching full URLs or “PR `#123`”) and show both patterns so
non-standard PR references are not missed; mention the exact `grep -oE
"#[0-9]+"` pattern in the note so reviewers can find and adjust it.

---

270-270: Consider checking if branch already exists.

When creating the feature branch, consider verifying it doesn't already exist to provide a clearer error message if there's a conflict.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 270, The step "Create a feature
branch (e.g., `changelog-v9.6.0-rc.1`)" should first verify the branch doesn't
already exist; update the command or instructions to run a branch-existence
check (for example using git rev-parse --verify or git branch --list) before
creating the branch and provide a clear error/helpful message if it exists, and
then proceed to create the branch only when the check passes so users see a
friendly conflict explanation instead of a confusing git failure.

---

269-269: Specify how to verify working tree state.

The instruction to "verify the working tree only has CHANGELOG.md changes" is good but could be more specific about the verification method.

💡 Suggested enhancement

Consider adding the specific command to check:

-   - Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
+   - Verify the working tree only has `CHANGELOG.md` changes using `git status --porcelain`; if there are other uncommitted changes, warn the user and stop

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/commands/update-changelog.md at line 269, Update the instruction
that currently says "verify the working tree only has `CHANGELOG.md` changes" to
include an exact git command and expected check; for example, tell the user to
run a command like `git status --porcelain` (or `git diff --name-only`/`git diff
--staged --name-only`) and verify the output contains only `CHANGELOG.md` (or is
empty except for that file), and instruct to abort if any other filenames
appear. Reference the `CHANGELOG.md` check text so editors know where to insert
the command and expected-success condition.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.claude/commands/update-changelog.md:
- Line 64: Update the sentence that currently reads "Check that the computed
version is newer than ALL existing tags (stable and prerelease)." to explicitly
cover the explicit-version path by changing it to "Check that the computed or
provided version is newer than ALL existing tags (stable and prerelease)." —
edit the line near the existing reference to the explicit-version option
(mentioned at line 13) in update-changelog.md so the wording covers both
computed and user-provided versions.
- Line 224: The PR extraction step uses the grep pattern `grep -oE "#[0-9]+"`,
which only matches GitHub-style “#123” references; update the documentation near
the `2. **Extract ALL PR numbers**` line to state this assumption and either (a)
add examples of other common reference formats to be aware of or (b) provide an
alternative extraction command (e.g., also matching full URLs or “PR `#123`”) and
show both patterns so non-standard PR references are not missed; mention the
exact `grep -oE "#[0-9]+"` pattern in the note so reviewers can find and adjust
it.
- Line 270: The step "Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)"
should first verify the branch doesn't already exist; update the command or
instructions to run a branch-existence check (for example using git rev-parse
--verify or git branch --list) before creating the branch and provide a clear
error/helpful message if it exists, and then proceed to create the branch only
when the check passes so users see a friendly conflict explanation instead of a
confusing git failure.
- Line 269: Update the instruction that currently says "verify the working tree
only has `CHANGELOG.md` changes" to include an exact git command and expected
check; for example, tell the user to run a command like `git status --porcelain`
(or `git diff --name-only`/`git diff --staged --name-only`) and verify the
output contains only `CHANGELOG.md` (or is empty except for that file), and
instruct to abort if any other filenames appear. Reference the `CHANGELOG.md`
check text so editors know where to insert the command and expected-success
condition.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bfc65a8a-4490-464a-a6f0-3fdab3b334a1

📥 Commits

Reviewing files that changed from the base of the PR and between b116cc2 and 9b61683.

📒 Files selected for processing (1)

• .claude/commands/update-changelog.md

[claude]

Review: Port update-changelog improvements from react_on_rails

Overall this is a solid improvement. The structural reorganization into named steps, the git-tags-only RC index fix, and the tag reconciliation step all address real pain points. A few things worth addressing:

Gap: explicit version + prerelease collapsing

Step 4, item 3 only mentions collapsing prior prerelease sections for rc/beta mode, but an explicit version like 9.7.0-rc.10 is semantically equivalent and should trigger the same behavior. Currently a user passing /update-changelog 9.7.0-rc.10 would skip collapsing v9.7.0-rc.9, v9.7.0-rc.8, etc. Suggest adding: 'For explicit RC/beta versions, apply the same prerelease collapsing as for rc/beta mode.'

Missing: commit message format for auto-commit

Step 5.6 instructs to automatically commit but doesn't specify a commit message format. Without guidance, the AI may use inconsistent messages. Suggest specifying something like: Update CHANGELOG.md for v9.6.0-rc.1.

Minor: Steps 3.3-3.4 overlap with Step 2

Step 3 still includes 'Also check if the tag is ahead of origin/main' which is already handled by the new Step 2 reconciliation. This creates redundant guidance — could be removed or reworded to reference Step 2.

Minor: no validation for invalid explicit versions

The argument parsing handles npm semver and RubyGems dot format, but doesn't specify what to do if an unrecognizable string is passed (e.g., /update-changelog foo). Worth a brief 'if the version cannot be parsed, abort with an error' note.

These are all relatively minor — the core changes are well-thought-out and the new structure is significantly clearer than the flat numbered list it replaces.

[claude]

The prerelease collapsing rule here only fires for rc/beta mode, but an explicit version argument like 9.7.0-rc.10 should trigger the same behavior. A user passing /update-changelog 9.7.0-rc.10 will currently skip collapsing v9.7.0-rc.9, v9.7.0-rc.8, etc.

Suggest updating to:

Suggested change

	3. For `rc`/`beta`: collapse prior prerelease sections of the same base version into the new section
	3. For `rc`/`beta` or an explicit prerelease version (e.g., `9.7.0-rc.10`): collapse prior prerelease sections of the same base version into the new section

[claude]

The auto-commit step doesn't specify a commit message format, which means different runs may produce inconsistent messages. Suggest adding a concrete format:

Suggested change

	- Push and open a PR with the changelog diff as the body
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit with message `Update CHANGELOG.md for vX.Y.Z` (using the stamped version)

[claude]

Items 3 and 4 here overlap with what Step 2 already handles. If Step 2 ran correctly, the tag-ahead-of-main scenario will have already been resolved. Consider removing or replacing these lines with a forward reference:

Suggested change

	1. Run `git log --oneline LATEST_TAG..origin/main` to find commits after the latest tag (LATEST_TAG is the most recent git tag, i.e., the same one identified in Step 2)
	2. **Extract ALL PR numbers** from commit messages: `git log --oneline LATEST_TAG..origin/main | grep -oE "#[0-9]+" | sort -u`
	3. Also check `git log --oneline origin/main..LATEST_TAG` to see if the tag is ahead of origin/main
	4. If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
	3. If Step 2 found no missing tagged versions, verify no tag is ahead: `git log --oneline origin/main..LATEST_TAG` should be empty

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6021dc5c28

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Handle draft headers before inferring missing tagged releases

This rule treats any mismatch between the latest git tag and the first changelog version header as proof that tagged releases are missing, but this workflow also explicitly allows a version header to exist before its tag is created; in that common pre-release window, the mismatch is expected and this logic will incorrectly trigger backfill behavior (creating/moving sections for versions that are not actually missing). The comparison should confirm that the latest tag is absent from changelog headers (or that the top header is older), rather than requiring exact equality with the top header.

Useful? React with 👍 / 👎.

[claude]

The explicit version description says it "skips auto-computation" but omits that the version still needs to be validated against existing tags. The PR description mentions "validation requiring it to be newer than existing tags" but this isn't captured in the instructions here, leaving the agent without a clear directive.

Suggested change

- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10` or `9.7.0.beta.2`), convert to npm semver dash format (`v9.7.0-rc.10` or `v9.7.0-beta.2`) for the changelog header.

- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10` or `9.7.0.beta.2`), convert to npm semver dash format (`v9.7.0-rc.10` or `v9.7.0-beta.2`) for the changelog header. **Validate** that the explicit version is newer than ALL existing tags; if not, warn the user and ask how to proceed.

[claude]

The "re-check" instruction at the end of this step is vague — the agent doesn't know what action to take when Step 2 should have caught something but didn't. It would be clearer to specify the recovery action (e.g., go back and run the Step 2 reconciliation logic for that tag).

Suggested change

	3. If Step 2 found no missing tagged versions, verify no tag is ahead of main: `git log --oneline origin/main..LATEST_TAG` should be empty. If not, entries in "Unreleased" may belong to that tagged version — Step 2 should have caught this, so re-check.
	3. If Step 2 found no missing tagged versions, verify no tag is ahead of main: `git log --oneline origin/main..LATEST_TAG` should be empty. If it is not empty, entries in "Unreleased" may belong to that tagged version — return to Step 2 and run the reconciliation logic for that tag before continuing.

[claude]

The branch check (must be on main) correctly guards against accidents, but doesn't handle the re-run scenario: if a previous run stamped the changelog but the push/PR creation failed, the user is now on a changelog-vX.Y.Z branch and would be blocked from retrying. Worth adding a note for this case.

Suggested change

	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	- Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
	- Verify the current branch is `main` (`git branch --show-current`); if not, warn the user and stop
	- Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit with message `Update CHANGELOG.md for vX.Y.Z` (using the stamped version)
	- Push and open a PR with the changelog diff as the body
	- If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
	- Remind the user to run `bundle exec rake create_release` (no args) after merge to publish and auto-create the GitHub release
	6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
	- Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
	- Verify the current branch is `main` (`git branch --show-current`); if not, check whether it looks like a changelog feature branch (e.g., `changelog-vX.Y.Z`) — if so, the previous run may have been interrupted after branching; ask the user whether to continue from the existing branch or abort. Otherwise warn and stop.
	- Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
	- Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit with message `Update CHANGELOG.md for vX.Y.Z` (using the stamped version)
	- Push and open a PR with the changelog diff as the body
	- If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
	- Remind the user to run `bundle exec rake create_release` (no args) after merge to publish and auto-create the GitHub release

[claude]

Review: Port update-changelog improvements from react_on_rails

Overall this is a solid improvement. The restructuring from a flat numbered list into named Steps (1–5) makes the workflow significantly clearer, and the key additions — git-tags-only RC index, tag reconciliation, duplicate-heading consolidation, and orphaned link cleanup — all address real failure modes.

Three specific issues flagged inline:

1. Explicit version validation is undocumented (line 13): The argument description says it "skips auto-computation" but doesn't mention that the version still needs to be validated as newer than all existing tags. The PR description calls this out as a feature, but the actual instructions don't tell the agent to enforce it.

2. Vague "re-check" recovery instruction (line 225): Step 3.3's fallback says "re-check" but doesn't specify what action to take, leaving the agent without a concrete recovery path when Step 2 should have caught a discrepancy.

3. No handling of interrupted re-runs (lines 267–274): The "must be on main" guard in the auto-commit step is correct for fresh runs, but will block a user who is already on a changelog-vX.Y.Z branch from a previous run that succeeded in branching but failed at push/PR creation. Worth adding a branch-name pattern check with a prompt to continue vs. abort.

No security, performance, or structural concerns — this is documentation only and the changes are well-scoped.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: da32b05997

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reconcile against all recent tags, not only the latest

This reconciliation rule only checks whether the single newest git tag appears anywhere in CHANGELOG.md, so it will miss gaps where an intermediate tagged release section is absent (for example, v9.8.0 exists in the changelog but v9.7.1 was accidentally omitted). In that case Step 2 reports “nothing missing,” Step 3 uses LATEST_TAG..origin/main, and the missing tagged section is never backfilled, which leaves release notes inconsistent with shipped tags.

Useful? React with 👍 / 👎.