Skip to content

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.md
index 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> 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 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 Request
2. Keep as-is (I'll handle it later)
-3. Discard this work
Which 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.
```bash
GIT_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