Custom Rebase

When To Use

Use for Fusion Framework branch refreshes where the agent must rebase onto origin/main, resolve common monorepo conflicts, and sanity-check the result before force-pushing.

Trigger phrases:

• "rebase this branch onto main"
• "refresh my branch"
• "fix rebase conflicts"
• "handle pnpm-lock.yaml conflicts"
• "generate a rebase report"

Required Gates

• Confirm the current branch and repository root before starting.
• Stop if the working tree is dirty unless the user explicitly says those changes are expected.
• Use pnpm only.
• Never run git reset --hard, git rebase --abort, git rebase --skip, or git push --force-with-lease without making the action and target branch explicit.
• Prefer origin/main as the rebase target unless the user gives another base.

Workflow

1. Prepare:

git status
git branch --show-current
git fetch origin
git fetch origin main:refs/remotes/origin/main

1. Rebase:

git rebase origin/main

1. Resolve known conflicts:

Then continue:

git rebase --continue

1. If .changeset/pre.json exists, packages bumped on main since next diverged won't automatically get a next-tagged release. Changesets v3 no longer tracks a baseline in pre.json.initialVersions (removed/unused upstream) — instead, create one consolidated changeset covering every package whose version increased on main during the rebase, so they pick up a next pre-release bump:

pnpm changeset status --verbose

Compare against the rebase diff to find packages whose package.json version increased purely from main's own "Version Packages" commits, then add one .changeset/*.md file listing all of them (patch bump, "Internal: rebase next onto main..." message). Do not resurrect the old align-pre-initial-versions.cjs baseline script — it edits a pre.json field Changesets v3 no longer reads.

Running pnpm changeset status (or changeset version) also auto-migrates pre.json to the v3 layout the first time it's called after upgrading past v3: previously-consumed pre-release changesets move from .changeset/.md into .changeset/pre/.md. This is expected, documented, one-time behavior — commit it as its own step rather than reverting it.

1. Check the local result against the remote branch:

BRANCH=$(git rev-parse --abbrev-ref HEAD)
git fetch origin
git diff --stat origin/$BRANCH...HEAD
git diff --name-only origin/$BRANCH...HEAD | sort
git log --oneline --left-right --cherry --no-merges origin/$BRANCH...HEAD
git push --force-with-lease --dry-run origin $BRANCH

1. Generate the raw report when risk or size warrants it:

node .agents/skills/custom-rebase/scripts/generate-rebase-report.cjs --no-fetch

Read the latest .tmp/skills/custom-rebase/*-rebase-report.md and summarize only the decision-relevant parts: largest diffs, dependency changes, package scope, pre.json changes, lockfile churn, validation to run, and push recommendation.

Troubleshooting

Expected Output

• Rebased branch or clear blocker
• Conflict decisions made explicit
• Remote comparison before push
• Human-readable risk summary when a report was generated
• Suggested validation commands before the user or agent pushes

Related Skills

• fusion-dependency-review for dependency PR analysis
• custom-dependency-pr-solver for Dependabot batch processing