finishing-a-development-branch

name	finishing-a-development-branch
description	Use when implementation is complete, all tests pass, and you need to integrate the work - automatically merges to base branch, pushes to remote, and cleans up the worktree

Finishing a Development Branch

Overview

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

Core principle: Verify tests → Merge to base → Push to remote → Clean up worktree.

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: Detect Environment

Determine workspace state before presenting options:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

This determines the cleanup behavior:

State	Cleanup
GIT_DIR == GIT_COMMON (normal repo)	No worktree to clean up
GIT_DIR != GIT_COMMON, named branch	Path-based (see Step 5)
GIT_DIR != GIT_COMMON, detached HEAD	No cleanup (externally managed)

Step 3: 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 4: Merge, Cleanup, and Push

Do not ask your human partner for a workflow choice. Perform the following automatically:

4a. Merge to Base Branch

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

git checkout <base-branch>
git pull
git merge <feature-branch>

Run tests on the merged result. If they fail, stop and report — do not proceed to push.

4b. Clean Up Worktree

Run Step 5 (Cleanup Workspace) now, while on the base branch.

4c. Delete Feature Branch

git branch -d <feature-branch>

4d. Push to Remote

git push origin <base-branch>

If no remote exists: Note it in your report and skip. Flag for your human partner.

If push fails (e.g., diverged history): Report the error. Do not force-push without an explicit request.

4e. No PR by default

Do not open a PR unless the original task brief explicitly requested one. Code review already happened inside the review loops — a PR adds friction with no benefit for solo development.

Step 5: Cleanup Workspace

Only runs for Step 4b (merge path). Skipped if we are already in a normal repo (no worktree).

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

If GIT_DIR == GIT_COMMON: Normal repo, no worktree to clean up. Done.

If GIT_DIR != GIT_COMMON and WORKTREE_PATH is under .worktrees/ or worktrees/ at the project root: This worktree was created by the using-git-worktrees skill — clean it up:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

If GIT_DIR != GIT_COMMON and the path is elsewhere: Do NOT remove the worktree. Leave it in place.

Quick Reference

Step	Action
1. Verify tests	Hard stop if failing
2. Detect environment	Normal repo vs. worktree
3. Determine base branch	Usually main
4a. Merge to base	Automatic
4b. Cleanup worktree	If applicable
4c. Delete feature branch	After merge + cleanup
4d. Push to remote	Automatic
4e. PR?	Only if task brief explicitly requested it

Common Mistakes

Skipping test verification

• Problem: Merging broken code
• Fix: Always verify tests before merging

Asking the human to choose a workflow

• Problem: Creates unnecessary friction and blocks async runs
• Fix: The workflow is automatic: merge → push. Only open a PR if explicitly requested.

Opening a PR by default

• Problem: Adds friction and implies human code review is needed, when it already happened
• Fix: Default is merge + push. PR is an opt-in, not the default.

Pushing before cleanup

• Problem: No real harm, but cleanup should happen first for logical ordering
• Fix: cleanup worktree → delete branch → push

Deleting branch before removing worktree

• Problem: git branch -d fails because worktree still references the branch
• Fix: Remove worktree (Step 5) first, then delete branch

Running git worktree remove from inside the worktree

• Problem: Command fails silently when CWD is inside the worktree being removed
• Fix: Always cd to main repo root before git worktree remove

Force-pushing

• Problem: Rewrites shared history
• Fix: Never force-push without an explicit request from your human partner

Red Flags

Never:

• Proceed with failing tests
• Merge without verifying tests on result
• Ask the human to choose a workflow (it's automatic)
• Open a PR unless the task brief explicitly asked for one
• Force-push without an explicit request
• Remove a worktree before confirming merge success
• Clean up worktrees you didn't create (path check)
• Run git worktree remove from inside the worktree

Always:

• Verify tests before merging
• Detect environment before cleanup
• Merge automatically — don't pause and ask
• Push after every successful merge
• cd to main repo root before worktree removal
• Run git worktree prune after removal