/merge-pr

name: merge-pr
description: Merge a pull request with status checks, squash merge, and branch cleanup. Handles worktree contexts.
disable-model-invocation: true
argument-hint: "[PR-number]"

Merge Pull Request

Merge a pull request with consistent practices: verify checks, squash merge, clean up the branch, and pull the latest base branch.

Command Options

• `$ARGUMENTS`: PR number (optional — defaults to the PR for the current branch)

Your task

Step 1: Identify the PR

• If a PR number was provided, use it
• Otherwise, detect from the current branch: `gh pr view --json number,title,state,headRefName,baseRefName`
• Confirm the PR exists and is open
• Display the PR title and number before proceeding

Step 2: Verify merge readiness

Check each of the following and report status:

• **CI status**: Run `gh pr checks` to verify all required checks have passed
• **Merge conflicts**: Run `gh pr view --json mergeable` to verify no conflicts
• **Review feedback**: Run `gh pr view --json reviewDecision,reviews` to surface any unresolved review threads or a pending "changes requested" — advisory, not a hard gate. (Carries over the review-thread awareness from the retired `/review-pr`.)

If CI has not passed, **stop and report**. Do not proceed with the merge.

Step 3: Merge the PR

• Squash merge: `gh pr merge --squash`
• Do **not** pass `--delete-branch` — GitHub is configured to auto-delete remote branches on merge. Local branch cleanup is handled in Step 4.

Step 4: Detect worktree context

Before updating local state, determine whether you are inside a git worktree:

git rev-parse --git-dir
git rev-parse --git-common-dir

• If these values are **identical**, you are in a normal repo — proceed with Step 5a.
• If they **differ**, you are in a worktree — proceed with Step 5b.

Step 5a: Update local state (normal repo)

After `gh pr merge` completes:

• Switch to the base branch (e.g., `main`, `master`, or whatever `baseRefName` was detected in Step 1) and pull: `git switch <base-branch> && git pull`
• Delete the local feature branch with `git branch -D <branch-name>` (force-delete is required because squash merges produce a different SHA, so `-d` cannot detect the branch as merged)

Then skip to Step 6.

Step 5b: Update local state (worktree)

When inside a worktree, `git switch` to the base branch will fail because it is checked out in another worktree. Handle this differently:

1. **Find the primary worktree** on the base branch:

   git worktree list --porcelain

Parse the output to find the worktree entry whose `branch` matches `refs/heads/<base-branch>`. Extract its path.

2. **Pull the base branch** from the primary worktree:

   git -C <primary-worktree-path> pull

3. **Do not delete the branch or remove the worktree automatically.** The branch cannot be deleted while it is checked out in a worktree, and removing the worktree would destroy the user's current working directory. Instead, provide the cleanup commands in the completion report.

Step 6: Confirm completion

**Normal repo** — report:

## Merge Complete

- PR: #N — [title]
- Remote branch: deleted
- Local branch: deleted (or kept — reason)
- Local <base-branch>: up to date

**Worktree** — report:

## Merge Complete

- PR: #N — [title]
- Remote branch: deleted
- Local <base-branch>: up to date (pulled in primary worktree)

## Worktree cleanup (run from outside this directory)

    git worktree remove <this-worktree-path>
    git branch -D <branch-name>

Important

• **Always squash merge.** This keeps main history clean with one commit per PR.
• **Do not merge if CI has not passed.** This is the one hard gate.
• **Do not amend or rewrite commits** as part of the merge process.
• **Squash merges require force-delete.** `git branch -d` cannot detect squash-merged branches, so `-D` is the correct flag for cleanup after a confirmed merge.