Finishing a development branch

Finishing a Development Branch

Overview

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

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

This determines which menu to show and how cleanup works:

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

Step 3: Determine Base Branch

<BASE_BRANCH> comes from the repository's Herdrpowers Configuration section. When it is declared, merge and PR targets are that branch — do not silently retarget main because it exists. Without a declared value, 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 <your best guess> - is that correct?" Confirm before merging: merging into the wrong base is expensive to undo.

Step 4: Present Options

Normal repo and named-branch worktree — present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push to origin and create a Pull Request
3. Push to origin only (no PR)
4. Keep the branch as-is (I'll handle it later)

Which option?

Detached HEAD — present exactly these 3 options:

Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as a new branch and create a Pull Request
2. Push as a new branch only (no PR)
3. Keep as-is (I'll handle it later)

Which option?

Present the menu exactly as written — concise, with every option coming from the list above. Discarding the work happens only in response to the user explicitly asking for it (see "If the user asks to discard the work" below).

Present, don't presume. Merging is one candidate among several, not the default ending. Never merge, push, or delete anything before the user names the option — and when they do, execute that option only.

Step 5: Execute Choice

Option 1: Merge Locally

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Scope check — this tree should be clean; anything here was written by mistake
git status --short

# Merge first — verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>

Every unexpected modification in that git status --short is a scope violation, not noise. A delegated pane whose task named a dedicated worktree has edited the main checkout instead, and it surfaced only because git merge refused with "Please commit your changes or stash them" — by which point the stray edit was one git stash away from riding into the merge commit unreviewed. Do not commit it, do not discard it: save it (git diff > <REPORT_DIRECTORY>/stray-<task>.patch), restore the file, finish the merge, and surface the patch to the user as its own decision.

If tests fail on the merged result: stop, leave the worktree and branch in place, and investigate — nothing has been pushed, so the merge is local and recoverable.

Once the merged result is green: clean up the worktree (Step 6), then delete the branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

Then create the pull/merge request against <base-branch> — not against main because it exists — with the forge's tooling: its CLI if one is available, or the creation URL most forges print when you push. Follow the repo's PR template and conventions if present, and report the URL to the user.

Keep the worktree — the user iterates on PR feedback there.

Option 3: Push Only

git push -u origin <feature-branch>

Report the pushed branch and its remote URL. Do not open a PR, and do not merge.

Keep the worktree — the branch is still live work.

Option 4: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

If the user asks to discard the work

This path exists only as a response to an explicit request to throw the work away. Confirm first:

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

Type 'discard' to confirm.

Wait for that exact confirmation. When it arrives:

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

Then clean up the worktree (Step 6) and force-delete the branch:

git branch -D <feature-branch>

Step 6: Cleanup Workspace

Runs for Option 1 and confirmed discards. Options 2, 3, and 4 always preserve the worktree. Both callers have already changed directory to the main repo root — worktree removal must run from outside the worktree — and use the GIT_DIR/GIT_COMMON/WORKTREE_PATH values captured in Step 2, from before that directory change.

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

If WORKTREE_PATH is under .worktrees/ or worktrees/: this pack created the worktree — we own cleanup:

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

If removal is refused (contains modified or untracked files): the worktree holds files that exist nowhere else — uncommitted plans, notes, or scratch work. Never --force on your own initiative. Show the user what is at stake and ask:

git -C "$WORKTREE_PATH" status --porcelain -uall

Worktree removal refused — these files were never committed:

<file list>

1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)

Which?

Carry out the choice, then remove the worktree.

Otherwise: The host environment owns this workspace — leave it in place. If your platform provides a workspace-exit tool, use it.

Quick Reference

Option	Merge	Push	Open PR	Keep Worktree	Cleanup Branch
1. Merge locally	yes	-	-	-	yes
2. Push + PR	-	yes	yes	yes	-
3. Push only	-	yes	-	yes	-
4. Keep as-is	-	-	-	yes	-
Discard (explicit request only)	-	-	-	-	yes (force)

Common Rationalizations

Excuse	Reality
"Tests passed earlier this session"	Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on.
"They obviously want it merged"	Integration is the user's decision. Present the menu and wait, then execute only the option they named.
"They seem done with this feature — I'll offer to discard it"	The menu is complete as written. Discard happens only when the user asks for it in so many words.
"'Yeah, get rid of it' counts as confirmation"	Only the typed word discard authorizes deletion.
"The PR is up, so the worktree is clutter now"	PR feedback gets fixed in that worktree. It stays until the work lands. Same for a bare push — the branch is still live work.
"This other worktree looks stale — I'll clean it too"	Clean up only worktrees under .worktrees/ or worktrees/. Everything else belongs to the host.
"Removal refused — --force is just finishing the cleanup"	The refusal means files exist only in that worktree. --force destroys them permanently. Show the user and ask.
"The merged-result failure is probably flaky"	A failing merged result stops everything. Branch and worktree stay put while you investigate.
"The base branch is obviously main"	<BASE_BRANCH> governs when declared; otherwise confirm the fork point or ask. Merging into the wrong base is expensive to undo.
"The push was rejected — force-push will fix it"	A rejected push means the remote moved. Investigate; force-push only on the user's explicit request.