finishing-a-development-branch

Finishing a Development Branch

Overview

Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.

Shell commands below use Bash syntax — run them in a Bash-capable shell such as Git Bash on Windows.

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

Step 1: Verify Tests

Run the project's full test suite (npm test / cargo test / pytest / go test ./...). If the project has no test suite, verification is whatever check the project does have (build, lint, smoke run); if there is none, ask the user what should gate completion.

If tests fail, report the failures and stop — the menu comes after a green suite:

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

[Show failures]

If tests pass: continue to Step 2.

Step 2: Detect Environment

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)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)
BRANCH=$(git branch --show-current)
echo "GIT_DIR=$GIT_DIR"
echo "GIT_COMMON=$GIT_COMMON"
echo "WORKTREE_PATH=$WORKTREE_PATH"
echo "BRANCH=${BRANCH:-<detached>}"

Note the printed values — shell variables do not persist between tool calls, and Step 6 needs them.

This determines which menu to show and how cleanup works:

State	Menu	Cleanup
GIT_DIR == GIT_COMMON (normal repo)	Standard 3 options	No worktree to clean up
GIT_DIR != GIT_COMMON, named branch	Standard 3 options	Provenance-based (see Step 6)
GIT_DIR != GIT_COMMON, detached HEAD	Reduced 2 options (no merge)	Externally managed — leave in place

Step 3: Determine Base Branch

The base branch is whatever this work forked from — usually named in the plan, the conversation, or the branch's upstream. If it is not already known, ask: "This branch split from - is that correct?" Confirm before merging: merging into the wrong base is expensive to undo.