fix(finishing-a-development-branch): handle worktree CWD cleanup ordering

[tartansandal]

Summary

• Rewrite Step 5 (Cleanup Worktree) with correct ordering: move CWD out first, remove worktree, prune refs, then delete branch
• Move branch deletion out of Option 1/4 inline code into Step 5 (which already handles it)
• Add cross-session plan guidance: warn that the executing session's CWD is inside the worktree
• Add two new Common Mistakes: "Removing worktree while CWD is inside it" and "Deleting branch before removing worktree"

Context

Discovered while using the skill to merge a feature branch from a git worktree. The previous Step 5 didn't account for:

1. CWD inside worktree: After git worktree remove, the shell's working directory no longer exists. Every subsequent command fails with "Path does not exist" — unrecoverable in the current shell.
2. Branch deletion ordering: git branch -d fails if the branch is still checked out in a worktree. The worktree must be removed first.
3. Cross-session plans: When the skill generates a plan for another session to execute (e.g. via executing-plans), the executing session's CWD is inside the worktree. The plan must warn about this.

Test Plan

• Subagent test: direct execution from inside worktree (Option 1 merge) — agent followed correct ordering
• Subagent test: plan generation for cross-session execution — plan included CWD warning and prefixed all commands with cd <main-repo>

Summary by CodeRabbit

• Documentation
  • Clarified steps for finishing development branches using git worktrees, emphasizing the correct order of operations for cleanup
  • Added explicit guidance on directory context requirements and potential issues when removing worktrees
  • Enhanced Quick Reference table and included rationale blocks explaining worktree removal sequencing

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

A documentation file for finishing a development branch is updated to clarify worktree cleanup procedures, reorganizing Steps 4 and 5 with explicit sequencing requirements, rationale blocks explaining common pitfalls, and warnings about working directory positioning relative to worktree removal.

Changes

Cohort / File(s)	Summary
Worktree Cleanup Documentation skills/finishing-a-development-branch/SKILL.md	Updated Step 4 options to clarify switching to base branch in main repo (not worktree); Step 5 rewritten to emphasize correct ordering—move working directory out of worktree before removal. Added explicit rationale blocks and warnings about directory positioning, updated Quick Reference table, and refined textual guidance throughout (+31/-13 lines).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• fix: Worktree cleanup fails when working directory is inside worktree #238: Addresses the same Step 5 worktree-removal flow concern, ensuring the working directory must be moved out of the worktree (cd to main repo) before executing git worktree remove.

Suggested reviewers

• yoavsion

Poem

🐰 A branch completed, time to clean,
Step out before removing the scene,
Order matters in the git ballet,
Worktree removed, the branch goes away,
Garden tidy—all is well! 🌿

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing worktree CWD cleanup ordering in the finishing-a-development-branch skill documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@skills/finishing-a-development-branch/SKILL.md`:
- Around line 130-160: The doc is inconsistent: "Step 5: Cleanup Worktree" now
says cleanup applies to Options 1, 2, 4 but the Quick Reference table and the
“Automatic worktree cleanup” common-mistakes section still imply a different
behavior for Option 2; update the Quick Reference table entry for Option 2 to
indicate that worktree cleanup is part of the process (matching "Options 1, 2,
4"), and revise the “Automatic worktree cleanup” mistake text to state the new
policy (cleanup occurs for Options 1, 2, 4; Option 3 keeps the worktree), add
the explicit warning text required for generated plans about CWD being inside
the worktree and that plans must either start with "cd <main-repo>" or note that
worktree removal will invalidate the shell.
- Around line 185-191: Replace the two bolded section titles "**Removing
worktree while CWD is inside it**" and "**Deleting branch before removing
worktree**" with proper ATX headings using "### Removing worktree while CWD is
inside it" and "### Deleting branch before removing worktree" in SKILL.md to
satisfy MD036; ensure the rest of the paragraph content under each heading
remains unchanged and that any references to these titles (e.g., in links or
TOC) are updated if necessary.

[arittr]

Thanks for the PR. The substantive cleanup-ordering work here has been superseded by #1121, now merged into dev.

The current finishing-a-development-branch flow detects the environment, avoids cleaning up worktrees for PR creation, moves out of the worktree before removal, removes/prunes worktrees before branch deletion, and documents the ordering pitfalls.

Closing this as superseded by the broader worktree rototill.