From e98a55de5f16fdf8086b4e1598494f5c0b3024ed Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sat, 30 May 2026 22:56:13 +0200 Subject: [PATCH] docs(skills): default post-merge worktree/branch cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pr-review §7a: after a PR merges, recommend tearing down the worktree and deleting the merged topic branch (local + origin) by default — state the action, let the user decline; never touch protected branches; git branch -d as the unmerged-work safety net. - whats-next §3c: document the worktree lifecycle — created at activation, removed by pr-review §7a at merge; prune stale worktrees before creating. Closes the gap that left empty worktrees parked at main's HEAD. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/pr-review/SKILL.md | 32 ++++++++++++++++++++++++++++++ .claude/skills/whats-next/SKILL.md | 7 +++++++ 2 files changed, 39 insertions(+) diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md index 02c2250c6..afec92fd9 100644 --- a/.claude/skills/pr-review/SKILL.md +++ b/.claude/skills/pr-review/SKILL.md @@ -312,6 +312,38 @@ tea pr close --login schweitz --repo jpmschweitzer/settled-reach Gitea does **not** auto-close PRs when you push a local merge — always close manually with `tea pr close` after pushing. +### 7a. Post-merge cleanup (default — suggest it, don't ask open-ended) + +Once a PR is merged and closed, its branch is fully contained in `main` and its +worktree is idle. **The default is to tear both down** — leaving them around is +how stale empty worktrees accumulate. So after the merge, *recommend* cleanup as +the default and proceed unless the user wants to keep them. Don't pose it as an +open question — state the default action, give the user a chance to decline. + +```bash +# 1. Remove the worktree (if the branch had one) +WORKTREE=$(git worktree list --porcelain | grep -B2 "branch refs/heads/" | grep "worktree " | sed 's/worktree //') +git worktree remove "$WORKTREE" # add --force only if it has uncommitted junk + +# 2. Delete the merged branch — local then origin +git branch -d # -d (not -D) refuses if not merged: a safety net +git push origin --delete +``` + +Safety rules: +- **Never delete protected branches** (`main`, `maintenance`, `server`, `client`, + `copy`, `audio`, `visual`, `ci`) — see `tea-cli.md`. Cleanup applies only to + topic branches. +- Use `git branch -d` (lowercase) — it refuses to delete a branch not merged into + HEAD, so it can't silently drop unmerged work. If it refuses, the branch isn't + actually merged: stop and investigate, don't reach for `-D`. +- This is safe because the commits live in `main` after the merge — but it is still + an outward action (deletes the origin branch). Recommend-and-proceed is fine for a + merged topic branch; if anything looks unmerged or shared, ask first. + +If `/whats-next` created the worktree (kanban flow), this is the step that closes +that loop — the worktree it spun up at activation is removed here at merge. + ### 8. Post-review actions **CHANGES_REQUESTED:** diff --git a/.claude/skills/whats-next/SKILL.md b/.claude/skills/whats-next/SKILL.md index 136ad6f92..7601831b4 100644 --- a/.claude/skills/whats-next/SKILL.md +++ b/.claude/skills/whats-next/SKILL.md @@ -192,6 +192,13 @@ git worktree add "$WORKTREE_DIR" Report the worktree path so the user can open a terminal there. +**Lifecycle:** a worktree created here is torn down at the *end* of the work, not +here. `/pr-review` §7a removes it (and deletes the merged branch) by default once +the PR merges. If you activate a batch and the work never ships, the worktree is +yours to clean up — don't leave empty worktrees parked at `main`'s HEAD (a sign of +an abandoned activation). Before creating a new worktree, `git worktree list` and +reuse or prune any stale one for the same branch. + ### 3d. Spawn implementation agents (optional) If the user wants agents, spawn them using general-purpose subagent_type