finishing-a-development-branch

Finishing a Development Branch

Overview

Guide completion of development work by verifying tests, then either executing a stated integration intent or presenting clear options.

Core principle: Verify tests → Detect environment → Honor stated integration intent or 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 integrating or presenting options, verify tests pass.

Follow verification-before-completion: run the suite, or reuse in-task evidence when Evidence reuse applies (same claim, same HEAD, relevant paths unchanged, full output still in context). Do not re-run a full suite solely because this skill's Step 1 repeats a verification you just completed under those conditions.

# Run project's test suite (when reuse does not apply)
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 or executing intent:

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 which menu to show (when needed) 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 finish-options)
GIT_DIR != GIT_COMMON, detached HEAD	Reduced 3 options (no merge)	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: Integration Intent or Present Options

If your human partner already specified the integration action (e.g. "open a PR", "merge to dev", "PR then merge"), skip the menu: map that instruction to the matching option below and go to Step 5. Present the menu only when intent is absent or conflicting.

Normal repo and named-branch worktree — when showing the menu, present exactly these 4 options:

Implementation complete. What would you like to do?

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

Which option?

Detached HEAD — when showing the menu, present exactly these 3 options:

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

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

Which option?

Don't add explanation - keep options concise.

Step 5: Execute Choice

After the user picks an option (or after mapping stated intent to an option), Read skills/finishing-a-development-branch/references/finish-options.md for per-option commands, confirmation prompts, and workspace cleanup (Options 1 and 4 only).

Common Mistakes

Skipping test verification

• Problem: Merge broken code, create failing PR
• Fix: Always verify tests (run or valid Evidence reuse) before integrating or offering options

Open-ended questions when intent is absent

• Problem: "What should I do next?" is ambiguous
• Fix: Present exactly 4 structured options (or 3 for detached HEAD). If intent was already stated, execute it—do not re-ask.

Cleaning up worktree for Option 2

• Problem: Remove worktree user needs for PR iteration
• Fix: Only cleanup for Options 1 and 4

Deleting branch before removing worktree

• Problem: git branch -d fails because worktree still references the branch
• Fix: Merge first, remove worktree, 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

Cleaning up harness-owned worktrees

• Problem: Removing a worktree the harness created causes phantom state
• Fix: Only clean up worktrees under .worktrees/ or worktrees/

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
• Remove a worktree before confirming merge success
• Clean up worktrees you didn't create (provenance check)
• Run git worktree remove from inside the worktree

Always:

• Verify tests before integrating or offering options (run or valid Evidence reuse)
• Detect environment before presenting menu or executing intent
• When intent is absent: present exactly 4 options (or 3 for detached HEAD)
• When intent is already stated: execute that action after verification—do not show the menu
• Get typed confirmation for Option 4
• Clean up worktree for Options 1 & 4 only
• cd to main repo root before worktree removal
• Run git worktree prune after removal