Finish Branch - Post-Merge Cleanup

Overview

This skill handles the cleanup after a PR has been merged. It will:

Verify the PR is actually merged (REQUIRED before any cleanup)
Delete the git worktree
Delete the local and remote branch
Close any related GitHub issues

IMPORTANT: This skill will NOT delete anything unless the PR is confirmed merged.

Usage

Invoke this skill when:

Your PR has been merged and you want to clean up
You finished an experiment and the results are merged to main
You need to remove an old worktree after successful merge

Workflow

Step 1: Identify the Branch and PR

First, ask the user which branch to clean up:

Which branch would you like to finish?

Please provide:
1. Branch name (e.g., exp/cot-faithfulness or feature/add-dark-mode)
2. PR number (if known) or I can find it

Step 2: Verify PR is Merged

CRITICAL: Before any deletion, verify the PR is merged:

# Find PR for the branch
gh pr list --head {branch-name} --state merged

# Or check specific PR
gh pr view {pr-number} --json state,mergedAt

# The PR MUST have state: "MERGED" before proceeding

If the PR is NOT merged:

## Cannot Proceed

The PR for branch '{branch-name}' is not yet merged.
Current state: {state}

Options:
1. Wait for the PR to be merged, then run /finish-branch again
2. Merge the PR now (if you have permissions)
3. Cancel cleanup

What would you like to do?

Step 3: Find Related Issues

# Get the PR body and look for issue references
gh pr view {pr-number} --json body,closingIssuesReferences

# Common patterns to find:
# - "Closes #123"
# - "Fixes #123"
# - "Resolves #123"
# - Issue links in PR body

Step 4: Delete Worktree (if exists)

# List worktrees to find the one for this branch
git worktree list

# Remove the worktree
# The worktree path is usually ../worktree-{name} or ../experiment-{name}
git worktree remove ../worktree-{name}

# If the worktree has uncommitted changes, force removal (after user confirmation)
git worktree remove --force ../worktree-{name}

Step 5: Delete Local and Remote Branch

# Delete local branch
git branch -d {branch-name}

# If the branch wasn't fully merged (shouldn't happen if PR is merged)
# Ask user before force deleting
git branch -D {branch-name}

# Delete remote branch
git push origin --delete {branch-name}

Step 6: Close Related Issues

# Close each related issue
gh issue close {issue-number} --comment "Closed via merged PR #{pr-number}"

Step 7: Report Results

## Branch Cleanup Complete

**Branch**: {branch-name}
**PR**: #{pr-number} (merged at {merged-at})

### Cleanup Actions
- [x] PR verified as merged
- [x] Worktree removed: ../worktree-{name}
- [x] Local branch deleted: {branch-name}
- [x] Remote branch deleted: origin/{branch-name}
- [x] Related issues closed: #{issue-1}, #{issue-2}

### Notes
{any-warnings-or-notes}

Error Handling

PR Not Found

Could not find a PR for branch '{branch-name}'.

Options:
1. Provide the PR number manually
2. Check if the branch was pushed to remote
3. Cancel cleanup

Worktree Not Found

No worktree found for branch '{branch-name}'.
This is fine if you were working in the main repository.

Proceeding with branch deletion...

Branch Has Unmerged Commits

WARNING: Branch '{branch-name}' has commits not in the merged PR.

Unmerged commits:
- {commit-hash}: {commit-message}

Options:
1. Force delete anyway (lose these commits)
2. Cherry-pick commits to a new branch first
3. Cancel cleanup

Issue Close Failed

Could not close issue #{issue-number}: {error}

This might be because:
- Issue doesn't exist
- Issue is already closed
- Insufficient permissions

Proceeding with other cleanup tasks...

Safety Checks

This skill includes several safety measures:

PR merge verification is mandatory - Will not proceed without confirmed merge
User confirmation for force operations - Always asks before force deleting
Unmerged commit detection - Warns if local branch has extra commits
Detailed reporting - Shows exactly what was deleted

Examples

Basic Usage

User: /finish-branch
Assistant: Which branch would you like to finish? Please provide the branch name or PR number.

User: exp/mi-estimation, PR #42
Assistant: Let me verify PR #42 is merged...
[Checks PR status]
PR #42 is merged. Proceeding with cleanup...
[Performs cleanup]
Branch cleanup complete!

With Related Issues

User: /finish-branch feature/add-auth
Assistant: Found PR #55 for branch feature/add-auth.
PR is merged (merged 2 hours ago).
Found related issues: #50 (Closes), #51 (Fixes)

Proceeding with cleanup...
- Removed worktree: ../worktree-add-auth
- Deleted branch: feature/add-auth
- Closed issue #50
- Closed issue #51

All done!

Integration with Research Executor

The research-executor agent MUST use this skill for cleanup. The workflow is:

Research executor creates worktree using /using-git-worktrees skill
Experiment is implemented with TDD methodology
PR is created and submitted for review
ONLY AFTER PR is merged, invoke /finish-branch for cleanup

The research-executor will prompt:

Experiment complete and PR merged!
Would you like me to clean up the worktree and branch?

Upon confirmation, invoke /finish-branch with the experiment branch name.

Critical Rules:

NEVER delete worktrees before PR is merged
NEVER delete worktrees manually - always use this skill
This is the ONLY approved cleanup method for experiment branches

This ensures experimental worktrees don't accumulate and the repository stays clean.

Related Skills and Agents

/using-git-worktrees - Creates the worktree (this skill cleans it up)
research-executor agent - The primary user of this skill for experiment cleanup
/google-docs-formatter - Used by research-executor for documentation