---
name: "finishing-a-development-branch"
description: "Decide how to integrate finished work once implementation is done and tests pass - verifies tests, detects the environment, determines the base branch, then presents structured options (merge, open a PR, keep the branch, or discard) and cleans up the workspace or worktree afterward. Triggers: I am done with this branch, wrap this up, merge this, should I open a PR, finish the feature, clean up the worktree, what do I do with this branch now."
---

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

**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 test suite (npm test / cargo test / pytest / go test ./... as appropriate). If tests fail: report "Tests failing (<N> failures). Must fix before completing" with the failures shown, and stop — do not proceed to Step 2. If tests pass, continue.

## Step 2: Detect Environment
Determine workspace state:
```
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)
```
- `GIT_DIR == GIT_COMMON` (normal repo): standard 4 options, no worktree cleanup needed.
- `GIT_DIR != GIT_COMMON`, named branch (worktree): standard 4 options, provenance-based cleanup (Step 6).
- `GIT_DIR != GIT_COMMON`, detached HEAD: reduced 3 options (no merge), no cleanup (externally managed).

## Step 3: Determine Base Branch
Try `git merge-base HEAD main` or `git merge-base HEAD master`, or ask the user to confirm the base branch.

## Step 4: Present Options
Normal repo / named-branch worktree — present exactly these 4, no extra explanation:
```
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 — present exactly these 3:
```
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?
```

## Step 5: Execute Choice
**Merge locally:** cd to main repo root (`git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel`), checkout base branch, pull, merge feature branch, re-run tests on the merged result. Only after merge succeeds: cleanup worktree (Step 6), then `git branch -d <feature-branch>`.
**Push and create PR:** `git push -u origin <feature-branch>`. Do NOT clean up the worktree — the user needs it to iterate on PR feedback.
**Keep as-is:** report "Keeping branch <name>. Worktree preserved at <path>." Don't clean up.
**Discard:** require the user to type the exact word "discard" to confirm, after showing exactly what will be deleted (branch, commits, worktree). If confirmed: cd to main repo root, cleanup worktree (Step 6), then `git branch -D <feature-branch>` (force).

## Step 6: Cleanup Workspace (only for Merge and Discard)
```
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, nothing to clean up, done.
If the worktree path is under `.worktrees/` or `worktrees/`: you (this skill set) created it — 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
```
Otherwise: the host/harness owns this workspace — do NOT remove it.

## Common Mistakes to Avoid
Skipping test verification before offering options. Open-ended questions instead of the exact structured menu. Cleaning up the worktree for Option 2 (PR) — user needs it alive. Deleting the branch before removing the worktree (fails because worktree still references it) — always merge first, remove worktree, then delete branch. Running `git worktree remove` from inside the worktree being removed — always cd to main repo root first. Cleaning up a harness-owned worktree — check provenance (`.worktrees/`/`worktrees/` path) first. Skipping typed confirmation for Discard.

## Red Flags
Never: proceed with failing tests, merge without verifying tests on the merged result, delete work without confirmation, force-push without explicit request, remove a worktree before confirming merge success, clean up worktrees you didn't create, run worktree remove from inside the worktree.
Always: verify tests before offering options, detect environment first, present exactly the right number of options, get typed confirmation for discard, clean up worktree only for merge/discard, cd to main root before removal, run worktree prune after removal.