diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md index 7f5337aa..368829fd 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 - 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 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 # 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 git push -u origin ``` +Then create the pull/merge request against 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 . Worktree preserved at ." **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 @@ -160,7 +171,7 @@ git branch -D ### 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