Finishing A Development Branch

What This Skill Does

This skill guides the agent through the process of completing development work on a branch, ensuring tests pass, presenting clear options for merging or pushing the code, and executing the chosen workflow. It emphasizes verifying tests before proceeding and cleaning up the worktree afterwards. This is useful for finalizing development tasks.

When to Use

• Merging a feature branch back to the main branch.
• Creating a pull request for code review.
• Keeping a branch as-is for later work.
• Discarding a branch after experimentation.
• Preparing a branch for deployment.
• Integrating changes from a feature branch.

Key Features

• Verifies tests pass before proceeding.
• Determines the correct base branch for merging.
• Presents clear options for completing the work.
• Executes the chosen option (merge, PR, keep, discard).Cleans up the worktree after completing the task.
• Creates a pull request with a summary and test plan.

## Overview

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

Core principle: Verify tests → 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: Present Options

Present exactly these 4 options:

Implementation complete. What would you like to do?

Merge back to <base-branch> locally Push and create a Pull Request Keep the branch as-is (I'll handle it later) Discard this work

Which option?

Don't add explanation - keep options concise.

Step 4: Execute Choice

Option 1: 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 5)

Option 2: 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: Cleanup worktree (Step 5)

Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

Don't cleanup worktree.

Option 4: Discard

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 5)

Step 5: Cleanup Worktree

For Options 1, 2, 4:

Check if in worktree: git worktree list | grep $(git branch --show-current)

If yes: git worktree remove <worktree-path>

For Option 3: Keep worktree.

Quick Reference

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

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

No confirmation for discard Problem: Accidentally delete work Fix: Require typed "discard" confirmation

Red Flags

Never: Proceed with failing tests 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 1 & 4 only

Integration

Called by: subagent-driven-development (Step 7) - After all tasks complete executing-plans (Step 5) - After all batches complete

Pairs with: using-git-worktrees - Cleans up worktree created by that skillFinishing a Development Branch

Overview

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

Core principle: Verify tests → 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: Present Options

Present exactly these 4 options:

Implementation complete. What would you like to do?

Merge back to <base-branch> locally Push and create a Pull Request Keep the branch as-is (I'll handle it later) Discard this work

Which option?

Don't add explanation - keep options concise.

Step 4: Execute Choice

Option 1: 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 5)

Option 2: 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: Cleanup worktree (Step 5)

Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

Don't cleanup worktree.

Option 4: Discard

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 5)

Step 5: Cleanup Worktree

For Options 1, 2, 4:

Check if in worktree: git worktree list | grep $(git branch --show-current)

If yes: git worktree remove <worktree-path>

For Option 3: Keep worktree.

Quick Reference

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

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

No confirmation for discard Problem: Accidentally delete work Fix: Require typed "discard" confirmation

Red Flags

Never: Proceed with failing tests Merge without verifying tests on result Delete work without confirmation Force-push without explicit re