rush-change

name	rush-change
description	Generate a Rush change file for the current branch, handling merge-commit false positives automatically. Run with /rush-change.

Rush Change — Smart Change File Generator

This skill generates a Rush change file for the current branch. It detects merge-commit false positives (where rush change --verify flags packages that have no real diff against main) and handles them automatically.

Important: How Rush Lockstep Versioning Works

All publishable packages use lockstep versioning — they share the same version number. Rush will always flag @grackle-ai/cli as the package needing a change file, regardless of which package you actually changed. This is because Rush picks one representative package from the lockstep group.

The change file is always created for @grackle-ai/cli, but the comment and bump type should describe ALL the changes in your PR across ALL packages. For example, if you changed packages/server/ and packages/mcp/, the change file is still for @grackle-ai/cli but the comment should describe the server and MCP changes.

Step 1: Check if Rush Requires a Change File

git fetch origin
node common/scripts/install-run-rush.js change --verify 2>&1

If this passes (exit 0), no change file is needed. Report success and stop.

Step 2: Determine Real vs False-Positive Changes

Rush says a change file is needed. Now determine whether publishable packages actually changed, or if this is a merge-commit false positive.

Get the net committed diff against main (explicit two-ref diff — compares branch tip to origin/main, ignoring merge commit artifacts and uncommitted changes):

git diff --name-only origin/main HEAD

Check if any of the changed files fall within a publishable package directory:

• packages/cli/
• packages/common/
• packages/powerline/
• packages/server/
• packages/adapter-sdk/
• packages/mcp/

Case A: Real changes in publishable packages

If the diff touches publishable package directories, this is a real change that needs a proper change file.

1. Examine the diff to determine the appropriate bump type:

   • patch — bug fixes, internal refactoring, dependency updates, test-only changes
   • minor — new features, new APIs, backwards-compatible additions
   • Never use major — CI blocks major bumps (pre-1.0)
   • Never use none for real changes — all publishable packages ship together in lockstep, so any real change (even test-only) should be patch or minor

2. Write a concise comment describing the change (what it does, not what files changed).

3. Get the commit email for the change file:

   git config user.email
   

4. Generate the change file:

   node common/scripts/install-run-rush.js change --bulk \
     --message "placeholder" \
     --bump-type patch \
     --email "$(git config user.email)"
   

5. IMPORTANT: You MUST edit the generated file. The --bump-type flag is unreliable and may produce "type": "none" regardless of what you passed. Find the generated JSON file in common/changes/@grackle-ai/cli/ and edit it:

   • Set "comment" to the real description
   • Set "type" to the correct bump type (patch or minor) determined above
   • Verify the file has the correct type before proceeding — do not trust --bump-type

Case B: False positive (merge-commit artifact)

If the diff does NOT touch any publishable package directories, Rush is flagging packages due to merge commits bringing in files from main. Generate a none change file:

node common/scripts/install-run-rush.js change --bulk \
  --message "placeholder" \
  --bump-type none \
  --email "$(git config user.email)"

No need to edit the comment — "placeholder" is fine for none type changes.

Step 3: Verify and Commit

Run verify again to confirm the change file satisfies Rush:

node common/scripts/install-run-rush.js change --verify

If it passes, commit:

git add common/changes/
git commit -m "Add rush change file"

If it still fails, read the error output and generate additional change files as needed (Rush may flag multiple packages in rare cases).

Step 4: Report

Summarize:

• Whether this was a real change or a merge-commit false positive
• The bump type and comment used
• The path of the generated change file