Finishing a Development Branch

Overview

Provide a structured, safe process for completing work on a development branch, including verification, merge strategy selection, and cleanup. This skill ensures no branch is merged without passing tests, and every destructive operation requires explicit user confirmation.

When to Use

• All planned work on a feature branch is complete
• A branch is ready for code review or merge
• Cleaning up after development work is finished
• Preparing a pull request for team review

Phase 1: Verify All Tests Pass

[HARD-GATE] Do NOT proceed to any merge or PR activity without passing verification.

Before any merge or PR activity, invoke verification-before-completion to confirm:

• All tests pass (unit, integration, e2e as applicable)
• No lint errors or warnings
• Build succeeds
• No untracked files that should be committed

# Run the project's full verification suite
# Do NOT skip this step even if "tests were passing earlier"

If verification fails, STOP. Fix the failures before proceeding. Do NOT create PRs or merge branches with failing tests.

STOP — Verification must pass before continuing to Phase 2.

Phase 2: Determine Base Branch

Identify the branch to merge into, using this detection logic:

Auto-Detection

# Check for common base branch names
git branch -a | grep -E 'remotes/origin/(main|master|develop)$'

# Check what branch was the fork point
git log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null
git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null

Base Branch Selection Decision Table

Verify Base Branch is Up to Date

git fetch origin
git log HEAD..<base-branch> --oneline

If the base branch has advanced since the feature branch was created, inform the user. They may want to rebase or merge base into the feature branch first.

Base Branch Divergence Decision Table

STOP — Confirm the base branch with the user before proceeding.

Phase 3: Present Merge Options

Present exactly these four options to the user. Do NOT add or remove options.

How would you like to finish this branch?

  A) Create PR    -- push and open a pull request for review
  B) Merge        -- merge into <base> with a merge commit
  C) Squash merge -- squash into one commit, merge into <base>
  D) Leave as-is  -- keep the branch, decide later

Option Selection Decision Table

STOP — Wait for user to select an option. Do NOT assume a default.

Phase 4: Execute Chosen Option

Option A: Create Pull Request

# Push the branch
git push -u origin <branch-name>

# Generate PR title from branch name or recent commits
# Generate PR body from commit messages and diff summary
gh pr create --title "<title>" --body "<body>"

PR Title Generation:

• Derive from branch name: feature/add-auth becomes Add authentication
• Keep under 70 characters
• Use imperative mood

PR Body Generation:

• Summarize the changes (what and why)
• List key modifications
• Note any breaking changes
• Include test plan

Option B: Merge Locally

# Switch to base branch
git checkout <base-branch>

# Merge feature branch
git merge <feature-branch>

# Delete the feature branch
git branch -d <feature-branch>

Confirmation required before executing the merge.

Option C: Squash Merge

# Switch to base branch
git checkout <base-branch>

# Squash merge
git merge --squash <feature-branch>

# Commit with a comprehensive message
git commit -m "<squash commit message>"

# Delete the feature branch
git branch -d <feature-branch>

Squash commit message should summarize all changes from the branch, not just the last commit.

Confirmation required before executing the squash merge.

Option D: Leave Branch As-Is

No action needed. Inform the user:

Branch <branch-name> left as-is.
You can return to it later with: git checkout <branch-name>

Phase 5: Cleanup

After executing options A, B, or C, perform cleanup:

Remove Worktree (if applicable)

If the branch was developed in a git worktree:

# Navigate out of the worktree first
git worktree remove <worktree-path>
git worktree prune

Clean Up Remote Tracking (Option B and C only)

If the branch was previously pushed:

# Delete remote branch after local merge
git push origin --delete <branch-name>

Confirmation required before deleting remote branches.

Verify Final State

git status
git log --oneline -5

Confirm the base branch is in the expected state.

Confirmation Requirements

[HARD-GATE] The following operations require explicit user confirmation before execution. Do NOT proceed on assumption. Always ask.

Anti-Patterns / Common Mistakes

Error Handling

Integration Points

Skill Type

RIGID — Follow this process exactly. Every phase must be completed in order. Do NOT skip verification. Do NOT merge without user confirmation. Do NOT assume a merge strategy. Do NOT delete branches without asking.