An agentic skills framework & software development methodology that works.
refactor(skills): stop offering to discard work in finishing-a-development-branch
Jesse Vincent9dff1a901f12
diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.mdindex 7f5337aaf..368829fd8 100644--- a/skills/finishing-a-development-branch/SKILL.md+++ b/skills/finishing-a-development-branch/SKILL.md@@ -1,6 +1,6 @@---name: finishing-a-development-branch-description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work---# Finishing a Development Branch@@ -50,22 +50,20 @@ This determines which menu to show and how cleanup works:| State | Menu | Cleanup ||-------|------|---------|-| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |-| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 3 options | No worktree to clean up |+| `GIT_DIR != GIT_COMMON`, named branch | Standard 3 options | Provenance-based (see Step 6) || `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |### Step 3: Determine Base Branch-```bash-# Try common base branches-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null-```--Or ask: "This branch split from main - is that correct?"+The base branch is whatever this work forked from — usually named in the+plan, the conversation, or the branch's upstream. If it is not already+known, ask: "This branch split from <your best guess> - is that correct?"+Don't guess silently: merging into the wrong base is expensive to undo.### Step 4: Present Options-**Normal repo and named-branch worktree — present exactly these 4 options:**+**Normal repo and named-branch worktree — present exactly these 3 options:**```Implementation complete. What would you like to do?@@ -73,25 +71,27 @@ Implementation complete. What would you like to do?1. Merge back to <base-branch> locally2. Push and create a Pull Request3. Keep the branch as-is (I'll handle it later)-4. Discard this workWhich option?```-**Detached HEAD — present exactly these 3 options:**+**Detached HEAD — present exactly these 2 options:**```Implementation complete. You're on a detached HEAD (externally managed workspace).1. Push as new branch and create a Pull Request2. Keep as-is (I'll handle it later)-3. Discard this workWhich option?```**Don't add explanation** - keep options concise.+Discarding the work is never offered. It exists only as a response to your+human partner explicitly asking for it (see "If your human partner asks to+discard the work" below).+### Step 5: Execute Choice#### Option 1: Merge Locally@@ -112,6 +112,10 @@ git merge <feature-branch># Only after merge succeeds: cleanup worktree (Step 6), then delete branch```+If tests fail on the merged result: STOP. Leave the worktree and branch in+place and investigate — nothing has been pushed, so the merge is local and+recoverable.+Then: Cleanup worktree (Step 6), then delete branch:```bash@@ -125,6 +129,11 @@ git branch -d <feature-branch>git push -u origin <feature-branch>```+Then create the pull/merge request against <base-branch> with the host's+tooling (`gh pr create`, `glab mr create`, or the URL git prints on push),+following the repo's PR template and conventions if present, and report+the URL to your human partner.+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.#### Option 3: Keep As-Is@@ -133,9 +142,11 @@ Report: "Keeping branch <name>. Worktree preserved at <path>."**Don't cleanup worktree.**-#### Option 4: Discard+#### If your human partner asks to discard the work++Never offer this. Only do it when your human partner explicitly asks to+throw the work away — and even then, confirm first:-**Confirm first:**```This will permanently delete:- Branch <name>@@ -160,7 +171,7 @@ git branch -D <feature-branch>### Step 6: Cleanup Workspace-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.+**Only runs for Option 1 and confirmed discards.** Options 2 and 3 always preserve the worktree.```bashGIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)@@ -188,7 +199,7 @@ git worktree prune # Self-healing: clean up any stale registrations| 1. Merge locally | yes | - | - | yes || 2. Create PR | - | yes | yes | - || 3. Keep as-is | - | - | yes | - |-| 4. Discard | - | - | - | yes (force) |+| Discard (explicit request only) | - | - | - | yes (force) |## Common Mistakes@@ -198,11 +209,15 @@ git worktree prune # Self-healing: clean up any stale registrations**Open-ended questions**- **Problem:** "What should I do next?" is ambiguous-- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)+- **Fix:** Present exactly 3 structured options (or 2 for detached HEAD)++**Offering to discard the work**+- **Problem:** Puts throwing away completed, passing work on the menu+- **Fix:** Discard only on your human partner's explicit request, never as an offer**Cleaning up worktree for Option 2**- **Problem:** Remove worktree user needs for PR iteration-- **Fix:** Only cleanup for Options 1 and 4+- **Fix:** Only cleanup for Option 1 and confirmed discards**Deleting branch before removing worktree**- **Problem:** `git branch -d` fails because worktree still references the branch@@ -225,6 +240,7 @@ git worktree prune # Self-healing: clean up any stale registrations**Never:**- Proceed with failing tests- Merge without verifying tests on result+- Offer discarding the work — it happens only on explicit request- Delete work without confirmation- Force-push without explicit request- Remove a worktree before confirming merge success@@ -234,8 +250,8 @@ git worktree prune # Self-healing: clean up any stale registrations**Always:**- Verify tests before offering options- Detect environment before presenting menu-- Present exactly 4 options (or 3 for detached HEAD)-- Get typed confirmation for Option 4-- Clean up worktree for Options 1 & 4 only+- Present exactly 3 options (or 2 for detached HEAD)+- Get typed confirmation before any discard+- Clean up worktree for Option 1 and confirmed discards only- `cd` to main repo root before worktree removal- Run `git worktree prune` after removal