resolve-pr-merge-conflicts

name	resolve-pr-merge-conflicts
description	Resolve a PR that conflicts with its base branch by rebasing onto the base and force-pushing with lease — never a merge commit. Use when a PR is out of date or has conflicts with main, when GitHub shows "This branch has conflicts that must be resolved", or when the user asks to rebase a branch, update a branch against main, or resolve PR conflicts.
allowed-tools	Bash(git *), Bash(gh *), Read, Edit

Resolve PR Merge Conflicts

Rebase-only. Never a merge commit. A PR that conflicts with its base is fixed by replaying this branch's commits on top of the updated base (git rebase), then git push --force-with-lease. git merge <base>, git pull without --rebase, and any move that lands a merge commit on the branch are forbidden — the goal is linear history. When a rebase gets hard, the only escape is git rebase --abort, never a merge. Plain git push --force is also forbidden; always --force-with-lease.

Asking the user: where a step says "ask the user", use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini/Pi. Fall back to asking in chat only when no blocking tool exists. Never silently skip the question.

Context

In Claude Code the labeled sections below are pre-populated — use them directly. On other platforms run the fallback block.

Current branch: !git branch --show-current

Working tree + in-progress state: !git status

Remote default branch: !git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'

PR state: !gh pr view --json url,title,state,baseRefName,mergeable 2>/dev/null || echo 'NO_OPEN_PR'

Context fallback

printf '=== BRANCH ===\n'; git branch --show-current; printf '\n=== STATUS ===\n'; git status; printf '\n=== DEFAULT_BRANCH ===\n'; git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'; printf '\n=== PR ===\n'; gh pr view --json url,title,state,baseRefName,mergeable 2>/dev/null || echo 'NO_OPEN_PR'

---

Step 1: Preflight

Resolve the base branch from the PR's baseRefName. If there is no PR, use the default branch (strip the origin/ prefix; if it returned DEFAULT_BRANCH_UNRESOLVED or bare HEAD, try gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name', else fall back to main).

Stop conditions — report and stop rather than improvise:

• On the base branch itself (not a feature branch) — nothing to rebase.
• A merge is already in progress (status shows "You have unmerged paths" from a merge, or a MERGE_HEAD exists) — this is the cheat mid-flight. Run git merge --abort, then continue this skill from the top.
• A rebase is already in progress — you are resuming; skip to Step 3.
• Dirty working tree with uncommitted changes — a rebase requires a clean tree. Ask the user whether to commit the changes first or git stash them (and reapply after). Do not proceed until clean.

Then fetch the latest base:

git fetch origin

If git merge-base --is-ancestor origin/<base> HEAD succeeds, the branch is already on top of the base — there is nothing to rebase. Report and stop.

Step 2: Rebase onto the base

git rebase origin/<base>

If it completes with no conflicts, go to Step 4.

Step 3: Resolve conflicts, then continue

For each conflicted file: open it, resolve every conflict marker by hand so the result is correct (keep both intents where both are needed — do not blindly take one side), then git add <file>. When all conflicts in the current step are staged:

git rebase --continue

Repeat for each replayed commit until the rebase finishes.

If a step is genuinely unresolvable, or the same conflicts keep recurring across commits, or you are not confident the resolution is correct — abort and re-approach:

git rebase --abort

--abort returns the branch to exactly where it started, losing nothing. From there, either retry (e.g. git rebase origin/<base> -X ..., or interactively drop/reorder) or ask the user how to resolve. Never resolve a hard rebase by merging.

Step 4: Force-push with lease

The rebase rewrote this branch's commits, so its history diverges from the remote. Push with lease so a teammate's concurrent push is not clobbered:

git push --force-with-lease

If it is rejected because the remote moved, git fetch origin and inspect what changed before re-attempting — do not fall back to plain --force.

Step 5: Verify and report

Confirm the branch is now on top of the base with linear history and no merge commit introduced:

git log --oneline --graph -15
git merge-base --is-ancestor origin/<base> HEAD && echo "on top of base"

The graph must be a straight line (no fork/merge nodes) and the ancestor check must pass. Report the branch, the base it was rebased onto, how many commits were replayed, and the PR URL. If a PR is open, note that it should now show no conflicts.