/wt:merge-pr - Merge PR and Clean Up Worktree
Description
Squash-merges an open GitHub PR for a story branch, deletes branches, and removes the local worktree. Designed for automated use from QA completion workflows.
Usage
/wt:merge-pr {STORY_ID}
/wt:merge-pr {STORY_ID} {PR_NUMBER}Examples
/wt:merge-pr WINT-1012
/wt:merge-pr WINT-1012 42Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
STORY_ID | Yes | — | Story identifier (e.g., WINT-1012) |
PR_NUMBER | No | *(discovered via gh)* | PR number to merge. If absent, discovered from branch name. |
What It Does
This slash command:
- Finds the open PR for the story branch (or uses provided PR number)
- Squash-merges the PR via GitHub
- Deletes the remote branch (handled by
--delete-branch) - Removes the local worktree
- Cleans up the local branch reference
- Pulls origin main to sync local with the merged changes
Workflow
- Discover PR (if
PR_NUMBERnot provided):gh pr list --head story/{STORY_ID} --state open --json number
- If no open PR found: WARNING "No open PR for story/{STORY_ID}. Skipping merge." Continue to step 4 (worktree cleanup).
- Verify PR is mergeable - Check PR status:
gh pr view {PR_NUMBER} --json mergeable,state
- If not mergeable: WARNING, attempt merge anyway (GitHub will reject if truly unmergeable).
- Squash-merge PR - Merge and delete remote branch:
gh pr merge {PR_NUMBER} --squash --delete-branch
- On success: record merge result. - On failure: WARNING, continue to worktree cleanup.
- Remove local worktree - Clean up the worktree directory:
git worktree remove tree/story/{STORY_ID}
- If fails (dirty tree): retry with --force - If still fails: WARNING, continue.
- Delete local branch - Remove the local branch reference:
git branch -D story/{STORY_ID}
- May already be gone from --delete-branch. Ignore errors.
- Prune worktree metadata - Clean up stale references:
git worktree prune - Pull origin main - Sync local main with the merged changes:
git pull origin main
- If fails: WARNING, continue. Local main being behind is non-blocking.
Output
After completion, always report:
PR MERGED AND CLEANED UP
story_id: {STORY_ID}
pr_number: {number}
merge_strategy: squash
branch_deleted: true | false
worktree_removed: true | falseIf no PR was found:
WORKTREE CLEANED UP (NO PR)
story_id: {STORY_ID}
pr_number: none
merge_strategy: skipped
branch_deleted: true | false
worktree_removed: true | falseThis structured output allows the calling orchestrator to parse results for CHECKPOINT.yaml and status updates.
Error Handling
All failures are non-blocking — each step is independent and continues regardless of prior step outcomes.
| Error | Action |
|---|---|
gh CLI not found | WARNING: "GitHub CLI (gh) not found. Skipping PR merge. Worktree cleanup only." |
| No open PR found | WARNING: Skip merge, proceed to worktree cleanup |
| PR merge fails | WARNING: Log error, continue to worktree cleanup |
| Worktree remove fails | WARNING: Retry with --force, log if still fails |
| Local branch delete fails | WARNING: Branch may already be gone, ignore |
| Not authenticated | WARNING: "gh auth required for PR merge. Skipping merge." |
git pull origin main fails | WARNING: Log error, continue. Local main sync is non-blocking. |
Notes
- All steps are non-blocking: a failure in any step does not prevent subsequent steps from executing
- Mirrors the fault-tolerance pattern from
/wt:finish - Squash merge produces a single clean commit on main
--delete-branchhandles remote branch deletion as part of the merge- The worktree cleanup runs even if no PR exists (handles edge cases where PR was manually closed)
- The
ghCLI must be installed and authenticated for PR operations