combine-prs

name	combine-prs
description	Compare two competing PRs implementing the same feature, identify strengths of each, and combine the best parts into a single branch. Use when comparing PRs, combining implementations, cherry-picking between PRs, or resolving competing approaches.
allowed-tools	Bash(gh *), Bash(git *)
disable-model-invocation	true

Arguments

• $ARGUMENTS - Two PR numbers or branch names to compare (e.g., "230 231" or "#230 #231")

If no arguments are provided, ask the user for two PR numbers.

Context

• Current branch: !git branch --show-current
• Git status: !git status --short
• Repo slug: !gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null | head -1
• Base ref: !git branch -r 2>/dev/null | grep -oE 'origin/(main|master)' | head -1
• Remotes: !git remote -v 2>/dev/null | head -6

Your task

Compare two PRs that implement the same feature, analyze strengths and weaknesses, present a comparison, and on approval combine the best parts into one branch.

Step 1: Parse arguments and fetch PR metadata

Extract two PR numbers from the arguments (strip any leading "#" characters). If branch names are given instead, find their associated PRs via gh pr list.

For each PR, fetch metadata:

gh pr view <number> --json number,title,body,headRefName,baseRefName,author,state,additions,deletions,changedFiles

Verify both PRs target the same base branch and address the same feature. If they do not appear related, warn the user and ask whether to proceed.

Step 2: Fetch and analyze both diffs

For each PR, get the full diff:

gh pr diff <number>

Also read the actual changed files from each branch to understand full context (not just diff hunks). Check out each branch temporarily or use git show <branch>:<file> to read files without switching.

Analyze each PR across these dimensions:

• Files changed - which files each PR touches
• Lines added/removed - scope of changes
• Package/module placement - where new code lives, architectural fit
• Code liveness - is the code wired in and working, or dead/placeholder code
• Test coverage - what tests exist, what is covered
• Fail-fast vs graceful fallback - error handling approach
• API design - interfaces, contracts, extensibility
• Architectural implications - impact on future work, dependency direction

Step 3: Present comparison table

Present a structured comparison to the user:

## PR Comparison: #<A> vs #<B>

| Dimension | #<A> | #<B> | Verdict |
|-----------|------|------|---------|
| Files changed | ... | ... | ... |
| Lines +/- | ... | ... | ... |
| Package placement | ... | ... | ... |
| Code liveness | ... | ... | ... |
| Test coverage | ... | ... | ... |
| Error handling | ... | ... | ... |
| API design | ... | ... | ... |
| Future implications | ... | ... | ... |

## Recommended Combination Strategy

Take from #<A>:
- ...

Take from #<B>:
- ...

Resulting branch: #<winner> (will be updated, #<loser> will be superseded)

Wait for the user to approve, modify, or reject the strategy before proceeding.

Step 4: Combine onto one branch

After user approval:

1. Determine the surviving PR. Use whichever branch has the better foundation (or whichever the user specified). Check it out.

2. Reset to base. Soft-reset to the merge base so all changes become staged:

git checkout <surviving-branch>
git reset --soft <base-branch>

3. Unstage everything so you can selectively apply the combined result:

git reset HEAD .

4. Apply the combined changes. Read the relevant files from both branches using git show <branch>:<file> and write the combined version that incorporates the best parts of each. This requires judgment — it is not a mechanical merge. For files where both PRs made changes:

   • Read both versions in full
   • Determine which parts to keep from each
   • Write the combined result

5. Stage and commit with a descriptive squashed commit message:

git add <files...>
git commit -m "$(cat <<'EOF'
<concise summary of the combined feature>

Combined from #<A> and #<B>:
- From #<A>: <what was taken>
- From #<B>: <what was taken>
EOF
)"

6. Force-push with lease to update the surviving PR:

git push --force-with-lease origin <surviving-branch>

Step 5: Update PR descriptions

Update the surviving PR body to note the combination:

gh pr edit <surviving-number> --body "$(cat <<'EOF'
<original or updated description>

---
Supersedes #<other-number>. Combined the best of both implementations:
- From #<other>: <what was taken>
- From this PR: <what was kept>
EOF
)"

Step 6: Handle the superseded PR

Ask the user whether to close the superseded PR. If approved:

gh pr close <other-number> --comment "Superseded by #<surviving-number>, which combines the best parts of both implementations."

If the user declines, leave it open but add a comment noting the relationship:

gh pr comment <other-number> --body "See #<surviving-number> for a combined implementation that incorporates the best of both PRs."

Step 7: Report

Summarize what was done:

## Combined PR Result

- **Surviving PR:** #<number> (<url>)
- **Superseded PR:** #<number> (<status>)
- **Commit:** <short-sha> - <message>
- **From #<A>:** <what was taken>
- **From #<B>:** <what was taken>

Failure Handling

Failure	Action
PR not found	Report and ask for correct number
PRs target different base branches	Warn user, ask to proceed
PRs are unrelated (no file overlap)	Warn user, ask to proceed
Merge conflicts during combination	Resolve manually, show user what was resolved
Force-push rejected	Report error, suggest git pull --rebase first
User rejects combination strategy	Ask what they want changed, revise the plan