finishing-a-development-branch Option 1: cleanup sequence fails inside worktree

[csillag]

Problem

The finishing skill's Option 1 (Merge Locally) has two cleanup bugs when running from inside a worktree — the expected context after worktree-based execution.

Bug 1: Branch deletion before worktree removal

After merging, the skill runs git branch -d <feature-branch> while the worktree still has that branch checked out. Git refuses:

error: cannot delete branch 'feature-branch' used by worktree at '/path/to/.worktrees/...'

The fix is to remove the worktree first, then delete the branch. The current order in the skill (Step 4 then Step 5) is reversed.

Bug 2: False "discard work" warning on already-merged commits

When removing the worktree after a successful merge, the worktree exit tool warns about discarding commits:

Worktree has 4 commits on feature-branch. Removing will discard this work permanently.

These commits were already fast-forward merged to the base branch — they are not at risk. The safety check should verify whether the branch's commits are reachable from the base branch before warning.

Reproduction

1. Use using-git-worktrees to create a worktree
2. Make commits on the feature branch
3. Invoke finishing-a-development-branch, choose Option 1
4. Observe: branch deletion fails, then worktree removal warns about already-merged commits

Suggested Fix

• Swap the order: remove worktree (Step 5) before deleting branch (end of Step 4)
• Before warning about discarding commits, check git merge-base --is-ancestor <feature-branch> <base-branch> — if true, the commits are already merged and removal is safe

Context

Found during manual testing of #997. These are pre-existing bugs, not introduced by that PR. Related: #167 (checkout failure from worktree, same Option 1 flow).

[bakathefish]

Proposed Fix

Two bugs in skills/finishing-a-development-branch/SKILL.md:

Bug 1: Branch delete before worktree removal (Option 1)

Option 1 (lines 69-86) runs git branch -d <feature-branch> while the worktree still has that branch checked out. Git rejects this with: "error: cannot delete branch used by worktree".

Fix: Move git branch -d <feature-branch> out of the Option 1 code block. Place it AFTER Step 5's git worktree remove:

#### Option 1: Merge Locally

\`\`\`bash
# Switch to base branch
git checkout <base-branch>

# Pull latest
git pull

# Merge feature branch
git merge <feature-branch>

# Verify tests on merged result
<test command>
\`\`\`

Then: Cleanup worktree (Step 5), then delete the feature branch:

\`\`\`bash
git branch -d <feature-branch>
\`\`\`

**Note:** The branch must be deleted AFTER worktree removal — git refuses to delete a branch that a worktree has checked out.

Bug 2: Step 5 contradicts Quick Reference table for Option 2

Step 5 (line 138) says: "For Options 1, 2, 4:" — cleanup worktree

Quick Reference table (line 153) says: Option 2 → Keep Worktree ✓

The table is correct — after creating a PR you may need the worktree for review changes.

Fix: Change Step 5 from "For Options 1, 2, 4:" → "For Options 1 and 4:"

And replace "Then: Cleanup worktree (Step 5)" after Option 2 with: "Worktree preserved — you may need it for PR review changes."

[obra]

Verified by Claude Code: fixed on the dev branch by commit 5dade17 — feat: rewrite finishing-a-development-branch with detect-and-defer (PRI-974). Step 6 in skills/finishing-a-development-branch/SKILL.md now cd "$MAIN_ROOT" before git worktree remove, and the Common Mistakes section explicitly documents both bugs from this issue (branch deletion before worktree removal; running git worktree remove from inside the worktree). Will ship with the next release.

— Claude Opus 4.7, Claude Code 2.1.112