finishing-a-development-branch

Finishing a Development Branch

Overview

Guide completion of development work by presenting clear options and handling chosen workflow.

Core principle: Verify tests → Run local finalization hook if present → Present options → Execute choice → Clean up.

Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

The Process

Step 1: Verify Tests

Before presenting options, verify tests pass:

# Run project's test suite
npm test / cargo test / pytest / go test ./...

If tests fail:

Tests failing (<N> failures). Must fix before completing:

[Show failures]

Cannot proceed with merge/PR until tests pass.

Stop. Don't proceed to Step 2.

If tests pass: Continue to Step 2.

Step 2: Determine Base Branch

# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main - is that correct?"

Step 3: Run Local Finalization Hook

Before presenting options, check whether the active agent/project/user environment defines a local ready-for-PR or finalization hook.

If present, run it first. It may require clean-tree checks, extra reviews, release checks, documentation updates, PR preparation, or external tooling. When it completes, continue here and present the normal options.

If no local hook exists, continue directly.

Step 4: Present Options

Present exactly these 4 options:

Implementation complete. What would you like to do?

1. Keep branch for local inspection
2. Merge back to <base-branch> locally
3. Push and create a Pull Request
4. Discard this work

Which option?

Don't add explanation - keep options concise.

Step 5: Execute Choice

Option 1: Keep branch for local inspection

# Keep the branch checked out for manual inspection
echo "Branch <name> preserved at <path>."

Don't cleanup worktree.

Option 2: Merge Locally

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

# Pull latest
git pull

# Merge feature branch
git merge <feature-branch>

# Verify tests on merged result
<test command>

# If tests pass
git branch -d <feature-branch>

Then: Cleanup worktree (Step 6)

Option 3: Push and Create PR

# Push branch
git push -u origin <feature-branch>

# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"

Then: Keep worktree (Step 6)

Option 4: Discard This Work

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation.

If confirmed:

git checkout <base-branch>
git branch -D <feature-branch>

Then: Cleanup worktree (Step 6)

Step 6: Cleanup Worktree

For Options 2 and 4:

Check if in worktree:

git worktree list | grep $(git branch --show-current)

If yes:

git worktree remove <worktree-path>

For Options 1 and 3: Keep worktree.

Quick Reference

Option	Merge	Push	Keep Worktree	Cleanup Branch
1. Keep for inspection	-	-	✓	-
2. Merge locally	✓	-	-	✓
3. Create PR	-	✓	✓	-
4. Discard	-	-	-	✓ (force)

Common Mistakes

Skipping test verification

• Problem: Merge broken code, create failing PR
• Fix: Always verify tests before offering options

Open-ended questions

• Problem: "What should I do next?" → ambiguous
• Fix: Present exactly 4 structured options

Skipping local finalization hooks

• Problem: User/project expects extra ready-for-PR checks before options
• Fix: Check for a local finalization hook before presenting options

Automatic worktree cleanup

• Problem: Remove worktree when might need it (Options 1, 3)
• Fix: Only cleanup for Options 2 and 4

No confirmation for discard

• Problem: Accidentally delete work
• Fix: Require typed "discard" confirmation

Red Flags

Never:

• Proceed with failing tests
• Present final options before an applicable local finalization hook runs
• Merge without verifying tests on result
• Delete work without confirmation
• Force-push without explicit request

Always:

• Verify tests before offering options
• Present exactly 4 options
• Get typed confirmation for Option 4
• Clean up worktree for Options 2 & 4 only

Integration

Called by:

• subagent-driven-development - After all reviewable slices complete
• executing-plans (Step 4) - After all phases complete

Pairs with:

• using-git-worktrees - Cleans up worktree created by that skill