krt-rebase-smith

Rebase Smith

Overview

Use this skill when the user wants to merge a derived branch without dragging history from another branch that was already merged (typical case: a branched from develop, b branched from a, and a is already merged).

Goal: keep the target branch clean by replaying only its own commits on top of the correct base branch.

Mandatory rules

Load references/safety.md before beginning the workflow.
Never guess the branch to rebase. Use the current branch or enclosing accepted workflow when unambiguous; otherwise ask.
Never assume develop exists: verify both local and remote.
If develop does not exist, ask which base branch to use (main, master, or another).
Refuse to rebase protected branches directly: main, master, develop.
Require a clean working tree before rebasing. If there are staged or unstaged changes, stop and ask whether to commit, stash, or cancel. Do not auto-stash unless explicitly approved.
Determine whether the target branch was branched from another feature branch whose commits should be dropped from the rewritten history. Ask only when this cannot be inferred.
Use rebase --onto when the target contains parent-branch commits that should not be replayed.
If the branch was already pushed, use --force-with-lease (never plain --force).
Show the exact push command and obtain confirmation before every push, including first publication with git push -u and rewritten history with --force-with-lease.
Do not merge branches or PRs. This skill may recommend a merge strategy, but it must only run a merge after the user explicitly approves that exact merge action.
Avoid destructive commands (reset --hard, push --force) unless explicitly requested.
Do not resolve conflicts silently. Present conflicted files and ask for direction unless the fix is obvious and the user asked for autonomous resolution.
Use the host runtime's command wrapper only when the current repo requires one. The command examples below use plain git for portability.
Use a single rebase-plan acceptance gate when acting standalone. If running inside an already accepted krt-release-marshal plan, and target/base/upstream are unambiguous, proceed with local rebase without a second local gate. Reuse its remote authorization only when that plan showed the exact push command and the current remote, branch/refspec, and push mode still match. Otherwise ask before any push, conflict-resolution choice, stash/drop operation, or other remote mutation.

Workflow

1) Preflight and branch discovery

Run:

git fetch origin --prune
git branch --show-current
git status --porcelain=v1 -b
git branch --list
git branch -r

Check whether develop exists locally or remotely:

git show-ref --verify --quiet refs/heads/develop || git show-ref --verify --quiet refs/remotes/origin/develop

If the working tree has staged or unstaged changes, stop before rebasing. Ask the user whether to commit, stash, or cancel.

2) Target branch resolution

If the target branch is obvious from the current branch or an enclosing accepted workflow, use it. Otherwise ask directly:

"Which branch do you want to rebase onto develop?"

Do not continue until the branch is known.

If the confirmed target is main, master, or develop, refuse to rebase it directly and ask for a non-protected feature branch.

3) Resolve base branch

If develop exists:

Base = origin/develop (preferred) or local develop if remote is not available.

If develop does not exist:

Ask: "I cannot find develop. Which base branch should we use for the rebase?"
Use the branch provided by the user.

4) Decide simple rebase vs rebase --onto

Determine whether <target> was branched from another feature branch whose commits are already merged into <base> and should be excluded. If this is not clear from branch history or an enclosing accepted workflow, ask.

If no parent feature branch needs to be dropped:

git log --oneline <base>..<target>

Plan a simple rebase:

git rebase <base>

If a parent feature branch or upstream commit should be dropped, resolve <upstream-to-drop>. This is usually the parent feature branch name, or the commit where <target> started.

Inspect the target-owned commits before planning:

git log --oneline <upstream-to-drop>..<target>

Plan a rebase --onto:

git rebase --onto <base> <upstream-to-drop> <target>

Use --fork-point only when normal merge-base detection would replay commits that are not owned by the target branch. Do not use it by default.

Present the selected rebase command as the rebase plan. Ask for approval when this skill is acting standalone. If an enclosing krt-release-marshal plan already accepted this exact rebase shape, proceed without a second approval gate.

5) Safe rebase

With <target> and <base> confirmed:

git switch <target>

Then run the planned command:

Simple rebase: git rebase <base>
Rebase onto: git rebase --onto <base> <upstream-to-drop> <target>

If conflicts appear:

git status
# resolve files
git add <resolved-files>
git rebase --continue

If the user decides to cancel:

git rebase --abort

6) Sync rewritten branch to remote

Check whether <target> exists on remote:

git ls-remote --heads origin <target>

If <target> already exists on remote:

git push --force-with-lease origin <target>

Before running this command, apply the exact push gate above. An accepted krt-release-marshal plan satisfies it only when it included this unchanged command; otherwise show it and ask for explicit confirmation because it rewrites remote branch history.

If it does not exist yet:

git push -u origin <target>

This first publication is also a remote mutation. Apply the same exact push gate: reuse an accepted krt-release-marshal plan only when it included this unchanged command; otherwise show it and ask for explicit confirmation.

7) Closeout and merge recommendation

Explain to the user that after rebasing, the PR from <target> to the selected base should show only commits owned by <target>. Do not merge the PR or branch unless the user explicitly approves that exact merge action.

Recommend merge strategy based on preference:

Squash and merge: one clean commit in final history.
Rebase and merge: preserves branch commits.
Avoid Merge commit if linear history is preferred.