abildtoft/kramme:pr:rebase

Rebase PR

Rebase the current branch onto the latest base branch and force push.

Why rebase — dev branches are costs

A feature branch is a cost that compounds every day it stays open. It drifts from the base branch, it accumulates irrelevant diff when other PRs land, and it forces every reviewer to re-learn a stale context. Rebasing is how you pay down that cost: the branch stays in sync with main, the diff stays scoped to the change, and the reviewer's mental model of the base is still valid when they open the PR. Merge commits defer the cost — they hide drift behind a merge marker instead of resolving it — which is why this skill rebases and force-pushes rather than merging main in. If the rebase fights you, that is evidence the branch is already too old: finish it or split it, don't patch it with more merges.

Options

Flags:

• --auto - Dangerous unattended mode. Continue through risky cases, bypass verification and confirmation gates, and push immediately with --force-with-lease after any completed rebase.
• --force-push - Safe unattended push mode. Skip only the final force-push confirmation and push immediately with --force-with-lease after a successful rebase, while keeping all conflict, red-flag, and verification gates.
• --base <branch> - Override auto-detected base branch (e.g., --base develop)

--force-push is the safe replacement for the old --auto behavior. It only bypasses the final confirmation prompt when the rebase completes without unresolved risk.

--auto is intentionally dangerous. It means: keep going through risky conflict resolution cases, do not stop for red-flag review, do not require verification before pushing, and push at the end once the rebase has completed. It still uses --force-with-lease; if the lease is rejected or the rebase cannot be completed mechanically, report that failure instead of inventing a new history.

Output markers

Use these uppercase markers when reasoning about the rebase and reporting progress. One marker per line, no decoration:

• REBASE PREFLIGHT — base branch, conflict method, and autostash state at the start. REBASE PREFLIGHT: origin/main, --autostash enabled, 3 uncommitted changes stashed.
• UNVERIFIED — claims about resolved conflicts that haven't been runtime-checked. UNVERIFIED: conflict auto-resolved in handler.ts but I didn't run the tests after.
• NOTICED BUT NOT TOUCHING — issues visible during rebase that are outside scope. NOTICED BUT NOT TOUCHING: origin/main has an unrelated lint failure — not this rebase's problem.
• CHANGES MADE / THINGS I DIDN'T TOUCH / POTENTIAL CONCERNS — end-of-run summary when the rebase completes.
• CONFUSION — ambiguous conflict evidence. CONFUSION: both sides of the conflict add the same function but with different signatures — unclear which is authoritative.
• MISSING REQUIREMENT — a decision is needed before the rebase can proceed. MISSING REQUIREMENT: origin/main has force-pushed since last fetch — confirm the target is correct before I continue.
• PLAN — announced sequence when conflicts span multiple rounds. PLAN: resolve handler.ts first, then re-run the rebase; 2 more files likely to conflict afterward.

Workflow

Step 0: Parse Arguments

If $ARGUMENTS contains --auto, set AUTO_MODE=true and remove the flag from remaining arguments. If $ARGUMENTS contains --force-push, set FORCE_PUSH_MODE=true and remove the flag from remaining arguments. If --base <branch> is present, set BASE_BRANCH_OVERRIDE=<branch> and remove the flag and value from remaining arguments.

If both --auto and --force-push are present, --auto wins because it is the broader dangerous mode. Continue with AUTO_MODE=true and ignore FORCE_PUSH_MODE.

Step 1: Validate Prerequisites

1. Check for rebase/merge in progress:

   ls -d .git/rebase-merge .git/rebase-apply .git/MERGE_HEAD 2> /dev/null
   

   If any exist, stop with error:

   "A rebase or merge is already in progress. Complete or abort it first with git rebase --abort or git merge --abort."

2. Resolve base branch:

   Use the shared plugin script to resolve the base branch. It uses the same 3-tier strategy as the sibling review skills: explicit --base, PR target branch (via gh), then origin/HEAD/origin/main/origin/master. It runs in strict mode and fetches the resolved base, so fetch failures stop the workflow with the script's stderr message.

   RESOLVE_ARGS=(--strict)
   [ -n "${BASE_BRANCH_OVERRIDE:-}" ] && RESOLVE_ARGS+=(--base "$BASE_BRANCH_OVERRIDE")
   
   RESOLVED=$("${CLAUDE_PLUGIN_ROOT}/scripts/resolve-base.sh" "${RESOLVE_ARGS[@]}") || {
     echo "Base resolution failed; see the message above. Re-run with --base <branch>." >&2
     exit 1
   }
   eval "$RESOLVED"
   

   The script exports BASE_REF, BASE_BRANCH, and MERGE_BASE. Use BASE_BRANCH wherever <base-branch> appears below.

3. Verify current branch is not the base branch:

   git branch --show-current
   

   If current branch equals base branch, stop with error:

   "You are on the base branch. Switch to a feature branch first."

Step 2: Fetch Latest

The resolve script in Step 1 already fetched origin/<base-branch>. If meaningful time has passed since Step 1 (e.g., after a long conflict round or user pause), refresh it before rebasing:

git fetch origin <base-branch>

Step 3: Rebase

Run the rebase with --autostash so uncommitted changes are stashed before the rebase and popped after, covering the common case of rebasing with local modifications:

git rebase --autostash origin/<base-branch>

If rebase succeeds: Proceed to Step 4.

If rebase fails (conflicts):

1. Attempt automatic resolution:

   The 10-round cap exists because each round reapplies a single commit; beyond that, conflicts almost always indicate semantic drift the auto-resolver can't handle safely. In normal and --force-push modes, escalate to the user instead of guessing further. In --auto mode, keep resolving until either the rebase completes or Git reaches a conflict the model cannot mechanically resolve.

   Track all conflicts and resolutions for the summary and set CONFLICTS_AUTO_RESOLVED=true once any conflict marker is resolved by the model. Before resolving each file, re-read the Red Flags section below. In normal and --force-push modes, abort instead of resolving when a red flag applies. In --auto mode, record that the red flag was bypassed and continue.

   For each round:

   a. Get list of conflicting files:

   git diff --name-only --diff-filter=U
   

   b. For each conflicting file:

   • Read the file content
   • Resolve conflict markers (<<<<<<<, =======, >>>>>>>) by analyzing both versions and choosing the best resolution
   • Record the conflict and resolution (file path, what conflicted, how it was resolved)
   • Write the resolved content back
   • Stage the file: git add <file>

   c. Continue the rebase (GIT_EDITOR=true prevents git rebase --continue from opening an editor on commit-message prompts):

   GIT_EDITOR=true git rebase --continue
   

   d. If rebase completes, proceed to Step 4: Conflict Summary

   e. If new conflicts arise, repeat from (a)

2. If resolution fails (after 10 rounds in normal or --force-push mode, or after an unresolvable conflict in any mode):

   Abort the rebase:

   git rebase --abort
   

   Inform user:

   "Automatic conflict resolution failed after X attempts. The branch has been restored to its pre-rebase state."

   "Conflicting files that could not be resolved: <list files>"

   "To resolve manually, run git rebase origin/<base-branch>, fix conflicts, then git rebase --continue."

Step 4: Conflict Summary (only if conflicts were resolved)

If the rebase completed without conflicts, skip to Step 5.

Otherwise, present a summary of what was auto-resolved. In normal and --force-push modes, this is review context before force pushing. In --auto mode, this is informational and does not block the push.

Conflicts resolved during rebase:

For each resolved conflict, show:

• File: <file path>
• Conflict: Brief description of what conflicted (e.g., "Both branches modified the calculateTotal function")
• Resolution: How it was resolved (e.g., "Combined changes: kept the new parameter from base branch and the validation logic from feature branch")

Step 5: Force Push

All force-push paths in this step must use this validated push procedure:

CURRENT_BRANCH=$(git branch --show-current)
git check-ref-format --branch "$CURRENT_BRANCH" >/dev/null
git push --force-with-lease origin "$CURRENT_BRANCH"

If AUTO_MODE=true, use the validated push procedure immediately after the rebase completes. Do this even if conflicts were auto-resolved, red flags were bypassed, or verification is unavailable/failing. Report the conflicts, bypassed red flags, and verification status after the push attempt. After this push attempt, skip the remaining confirmation gates and proceed to Step 6.

Before any FORCE_PUSH_MODE=true push, re-read the Red Flags section below. If any red flag applies, stop instead of pushing automatically and report MISSING REQUIREMENT: --force-push cannot bypass red-flag review; rerun without --force-push after addressing the concern. This applies even when the rebase completed without conflicts.

If FORCE_PUSH_MODE=true and CONFLICTS_AUTO_RESOLVED is not true, skip the confirmation prompt, use the validated push procedure immediately, then proceed to Step 6.

If FORCE_PUSH_MODE=true and CONFLICTS_AUTO_RESOLVED=true, do not push until one of these gates is satisfied:

1. Run the project's verification battery using the kramme:verify:run conventions. If verification is available and passes, use the validated push procedure.
2. If verification is unavailable, fails, or cannot cover the conflict resolution, present the full Conflict Summary and ask the user to confirm before pushing.

For the FORCE_PUSH_MODE=true conflict path, if neither gate succeeds, stop before git push and report:

• the full Conflict Summary
• verification command(s) attempted, if any
• why the branch was not pushed automatically

Use the UNVERIFIED marker for every conflict resolution that was not covered by a passing verification run.

If no earlier branch in this step has already pushed or stopped, use AskUserQuestion to confirm:

"Ready to force push rebased branch. This will overwrite the remote branch history. Continue?"

Options:

• Yes, force push - Push with --force-with-lease
• Do not push - Keep local rebase but don't push

If confirmed, use the validated push procedure.

Note: --force-with-lease refuses to overwrite remote commits you haven't fetched, providing safety against overwriting others' work.

Step 6: Report Results

Show the commit log relative to base (substitute the resolved base-branch name for <base-branch> — no spaces around the angle brackets, or the shell will read it as redirection):

git log --oneline origin/<base-branch>..HEAD

Confirm success:

"Branch rebased onto origin/<base-branch> and pushed."

Common Rationalizations

Lies you'll tell yourself mid-rebase. Each has a correct response:

• "I'll just merge main in instead — it's faster." → Faster now, harder to review later. Merges hide drift; rebases resolve it.
• "The auto-conflict resolution looks right — I don't need to re-run tests." → Conflict resolution is a code change. Re-run the verify battery or surface it as UNVERIFIED.
• "Force-push is fine; no one else is on this branch." → If the branch is pushed, assume someone has it. --force-with-lease is the floor, not the ceiling — still warn the user.
• "Ten rounds of auto-resolve failed — I'll just pick one side." → In normal and --force-push modes, the skill aborts after 10 rounds for a reason. Escalate to the user; don't guess. In --auto mode, continue only while the conflict remains mechanically resolvable.

Red Flags — STOP

Pause and hand back to the user if any of these are true:

• --force-with-lease is about to run against main, master, or develop.
• The auto-resolver merged logic from a file it doesn't fully understand.
• The rebase touched migration files or generated artifacts; auto-resolution is unsafe there.
• The branch hadn't been fetched recently and the base has moved significantly (>20 commits).
• Any conflict was resolved by deleting a block instead of merging semantics.

Exception: --auto bypasses these red-flag stops. When bypassing a red flag in --auto mode, record it in the end-of-run summary under POTENTIAL CONCERNS.

Verification

Before force-pushing, self-check:

• [ ] If conflicts were resolved, the Conflict Summary lists every resolved file with file + conflict + resolution. (No conflicts → this item is N/A.)
• [ ] If FORCE_PUSH_MODE=true and conflicts were machine-resolved, passing verification or explicit user confirmation happened before git push.
• [ ] If FORCE_PUSH_MODE=true, no red flags applied before the automatic push.
• [ ] If AUTO_MODE=true, all bypassed red flags and verification gaps are reported under POTENTIAL CONCERNS after the push attempt.
• [ ] The base branch was freshly fetched (Step 2 ran).
• [ ] The user explicitly confirmed via AskUserQuestion (Step 5), or FORCE_PUSH_MODE=true / AUTO_MODE=true allowed skipping confirmation.
• [ ] --force-with-lease (not --force) is the flag being used.
• [ ] Post-push git log --oneline origin/<base>..HEAD shows the expected linear history.