4.9 KiB
| name | description |
|---|---|
| finishing-a-development-branch | 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 ( 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 . Worktree preserved at ." 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.