| name | squash-merge-pr |
| description | Squash-merge a PR into its base branch. Invoke only when the user explicitly requests a squash merge. Single PR by number or current branch. Refuses on git-flow repos when the base is main — use /promote-release there instead. |
| metadata | {"argument-hint":"[PR_NUMBER]"} |
Squash Merge PR
Validates readiness, invokes /finalize-pr for soft blocks, then squash-merges.
Hard stops abort immediately. Some cases require human action: closed/merged PR,
draft, unresolvable conflicts, unrecoverable CI, or more than 100 review threads.
State warning: Branch state, remote tracking, and PR status change between
invocations. Re-run all git/gh commands from Step 1.
Critical Rules
- Run the GraphQL readiness gate on every invocation before merging
- PR metadata updates are
/finalize-pr's responsibility
- Invoke
/finalize-pr for soft blocks; abort on hard stops with reason
- Squash is never used to merge into
main on a git-flow repo — Step 0 guards this
Step 0: Refuse Squash Into Main On Git-Flow Repos
Resolve the PR's base branch and the repo's default branch:
BASE_BRANCH=$(gh pr view <PR_NUMBER> --json baseRefName --jq '.baseRefName')
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
If BASE_BRANCH == main AND DEFAULT_BRANCH == develop (repo is on git-flow —
see /gh-cli-patterns Canonical Default-Branch Detection), abort immediately,
no finalize:
"This is a develop → main promotion PR on a git-flow repo. main accepts
merge commits only — squash and rebase are banned by ruleset, no exceptions.
Run /promote-release instead, or merge manually with gh pr merge --merge."
Otherwise (trunk repo, or a git-flow repo's ordinary feature PR into develop),
continue to Step 1 — squash-merge remains the default there.
Step 1: Validate PR Ready
Run the canonical PR-readiness gate and canonical code-scanning alert count
from /gh-cli-patterns. Replace <OWNER>, <REPO>, <PR_NUMBER> per the
placeholder convention. CodeQL is separate from CI — check both.
1.1 Hard stops (abort immediately, no finalize)
| Condition | Message |
|---|
state != OPEN | "PR is closed or merged — nothing to do" |
isDraft == true | "PR is a draft — mark it ready for review first" |
human:review label present | "PR is gated on human review before merge (see pr-standards Human-Review Gate). Merge only on an explicit same-session user instruction to merge THIS PR; when so instructed, gh pr edit <PR_NUMBER> --remove-label human:review first, then proceed. Otherwise abort." |
reviewThreads.pageInfo.hasNextPage == true | ">100 review threads — paginate manually and re-verify before merging" |
1.2 Soft blocks (invoke /finalize-pr, then re-verify)
If any of the following fail, proceed to Step 1.3 (auto-finalize), then re-run the
full gate. If the gate still fails after finalization, abort with the specific reason.
| Check | Must be | Abort message (if still failing after finalize) |
|---|
mergeable | MERGEABLE | "PR has git conflicts — unresolvable" |
mergeStateStatus | CLEAN or HAS_HOOKS | "PR merge state is {value} — still blocked after finalize" |
reviewDecision | APPROVED or null | "Review decision is {value}" |
statusCheckRollup.state | SUCCESS | "CI is {state} — unrecoverable" |
All reviewThreads.isResolved | true | "Unresolved review threads remain" |
| CodeQL alert count | 0 | "Open CodeQL alerts remain — run /resolve-codeql manually" |
1.3 Auto-finalize
Invoke /finalize-pr <PR_NUMBER>. If it reports human intervention needed, abort with
its reason. Then re-run the full gate (Steps 1.1 + 1.2); if any soft block persists,
abort with the specific failing field.
Step 2: Generate Squash Commit Message
Analyze the full changeset to generate a release-note-friendly commit message.
Replace <PR_NUMBER> and <BASE_BRANCH> (from Step 0) before running:
git fetch origin <BASE_BRANCH>
git diff origin/<BASE_BRANCH>...HEAD
git log --oneline origin/<BASE_BRANCH>..HEAD
Generate:
- Title: Conventional commit format (
<type>: <description>, under 70 chars)
- Body: 2-3 line explanation of what changed and why
Types: feat, fix, refactor, docs, test, chore
Store the title in a shell variable:
SQUASH_TITLE="<generated title>"
Step 3: Execute Squash Merge
Capture the branch name before merging (needed for cleanup). Replace <PR_NUMBER> before running:
BRANCH=$(gh pr view <PR_NUMBER> --json headRefName --jq '.headRefName')
Merge without --delete-branch (avoids git switch failure in bare+worktree repos).
Use the heredoc body pattern from /gh-cli-patterns:
gh pr merge <PR_NUMBER> --squash --subject "$SQUASH_TITLE" --body "$(cat <<'EOF'
... generated body ...
EOF
)"
Single-quoted 'EOF' prevents shell expansion. Closing EOF must be alone on its own line with no leading whitespace.
Delete the remote branch (GitHub may have auto-deleted it on merge — || true handles that):
git push origin --delete "$BRANCH" || true
Find and remove the local worktree by branch name (works in any repo layout):
WORKTREE_PATH=$(git worktree list --porcelain | awk -v b="refs/heads/$BRANCH" '/^worktree/{p=$2} $0=="branch "b{print p}')
[ -n "$WORKTREE_PATH" ] && git worktree remove "$WORKTREE_PATH" || true
Delete the local branch ref (safe no-op if absent):
git branch -d "$BRANCH" || true
Step 4: Sync Base Branch
git switch <BASE_BRANCH>
git pull origin <BASE_BRANCH>
git worktree prune
Integration
Invoke at any time — auto-finalizes if needed:
/squash-merge-pr # Current branch PR
/squash-merge-pr 42 # Specific PR number
Related Skills
- finalize-pr (github-workflows) — invoked automatically by squash-merge-pr when blockers are found
- rebase-pr (github-workflows) — alternative merge strategy that preserves commit history
- promote-release (github-workflows) — the develop → main merge-commit path this skill refuses to substitute for
- pr-standards (git-standards) — PR authoring and review standards
- gh-cli-patterns (github-workflows) — canonical gh CLI command shapes, placeholder convention, PR-readiness gate, default-branch detection
