gh-pr-merge-unstable-state-needs-auto-and-watch-branch-deleteslisted
Install: claude install-skill wan-huiyan/agent-traffic-control
# `gh pr merge` UNSTABLE state + branch-delete recovery
## Problem
Two adjacent failure modes that read as "merge conflicts" but aren't:
### Failure A: `gh pr merge` rejects with "conflicts" when there are none
You push a clean resolution of merge conflicts, GitHub shows the PR as MERGEABLE, and yet:
```
$ gh pr merge 915 --squash
To have the pull request merged after all the requirements have been met,
add the `--auto` flag.
Run the following to resolve the merge conflicts locally:
gh pr checkout 915 && git fetch origin main && git merge origin/main
```
The first line is the actual hint; the second is misleading boilerplate. The real cause is
`mergeStateStatus: UNSTABLE` — branch protection or CI checks are pending. `gh` can't merge yet
because the repo's rules aren't satisfied, not because of file-level conflicts.
### Failure B: PR auto-closes if you delete the remote branch right after Failure A
Common pattern: previous PR on the same branch merged cleanly with `gh pr merge <N> --squash`. You
then do `git push origin --delete <branch>` to clean up. Habit kicks in for the next PR — you run
`gh pr merge` (gets Failure A above), notice the "conflicts" warning, run
`git push origin --delete <branch>` anyway thinking the merge already landed remotely...
```
$ gh pr view 915 --json state
{"state":"CLOSED"} # ← not MERGED — the PR closed because the branch was deleted with the merge un-queued
```
GitHub treats a deleted-branch PR with no merge in progress as abandon