From 227c26ca8dac1d8354d3a6e8ebdf2efc9c460449 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Sun, 5 Jul 2026 11:43:34 -0700 Subject: [PATCH] refactor(skills): compress finishing-a-development-branch, adopt rationalization table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Red Flags and Common Mistakes fold into one Common Rationalizations table (house Excuse/Reality form); every prior entry maps to a table row or an inline sentence in the step it guards. Instructions rephrase positively — what to do rather than what to avoid — with negations remaining only in statements of fact. Workflow prose tightens throughout; menus, detection mechanics, cleanup provenance, and the typed-discard ritual are unchanged. Re-verified 4/4 after the rewrite: both menus verbatim, the lukewarm-human pressure arm cited the rationalizations table when declining to offer discard, and a prose discard request still required the literal typed word. --- .../finishing-a-development-branch/SKILL.md | 153 ++++++------------ 1 file changed, 49 insertions(+), 104 deletions(-) diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md index e25420bc..7f6e4ec7 100644 --- a/skills/finishing-a-development-branch/SKILL.md +++ b/skills/finishing-a-development-branch/SKILL.md @@ -7,39 +7,25 @@ description: Use when implementation is complete, all tests pass, and you need t ## Overview -Guide completion of development work by presenting clear options and handling chosen workflow. - **Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up. **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work." -## The Process +## Step 1: Verify Tests -### Step 1: Verify Tests +Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`). -**Before presenting options, verify tests pass:** +**If tests fail**, report the failures and stop — the menu comes after a green suite: -```bash -# Run project's test suite -npm test / cargo test / pytest / go test ./... -``` - -**If tests fail:** ``` Tests failing ( failures). Must fix before completing: [Show failures] - -Cannot proceed with merge/PR until tests pass. ``` -Stop. Don't proceed to Step 2. +**If tests pass:** continue to Step 2. -**If tests pass:** Continue to Step 2. - -### Step 2: Detect Environment - -**Determine workspace state before presenting options:** +## Step 2: Detect Environment ```bash GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) @@ -52,16 +38,16 @@ This determines which menu to show and how cleanup works: |-------|------|---------| | `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) | +| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place | -### Step 3: Determine Base Branch +## Step 3: Determine Base Branch 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. +Confirm before merging: merging into the wrong base is expensive to undo. -### Step 4: Present Options +## Step 4: Present Options **Normal repo and named-branch worktree — present exactly these 3 options:** @@ -86,15 +72,15 @@ Implementation complete. You're on a detached HEAD (externally managed workspace Which option? ``` -**Don't add explanation** - keep options concise. - -Discarding the work is never offered. It exists only as a response to your +Present the menu exactly as written — concise, with every option coming +from the list above. Discarding the work happens only in response to your human partner explicitly asking for it (see "If your human partner asks to -discard the work" below). +discard the work" below). Wait for their answer; the integration decision +is theirs. -### Step 5: Execute Choice +## Step 5: Execute Choice -#### Option 1: Merge Locally +### Option 1: Merge Locally ```bash # Get main repo root for CWD safety @@ -108,24 +94,22 @@ git merge # Verify tests on merged result - -# 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. +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: +Once the merged result is green: clean up the worktree (Step 6), then +delete the branch: ```bash git branch -d ``` -#### Option 2: Push and Create PR +### Option 2: Push and Create PR ```bash -# Push branch git push -u origin ``` @@ -134,18 +118,16 @@ tooling — its CLI if one is available, or the creation URL most forges print when you 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. +Keep the worktree — your human partner iterates on PR feedback there. -#### Option 3: Keep As-Is +### Option 3: Keep As-Is Report: "Keeping branch . Worktree preserved at ." -**Don't cleanup worktree.** +### If your human partner asks to discard the work -#### 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: +This path exists only as a response to an explicit request to throw the +work away. Confirm first: ``` This will permanently delete: @@ -156,22 +138,23 @@ This will permanently delete: Type 'discard' to confirm. ``` -Wait for exact confirmation. +Wait for that exact confirmation. When it arrives: -If confirmed: ```bash MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) cd "$MAIN_ROOT" ``` -Then: Cleanup worktree (Step 6), then force-delete branch: +Then clean up the worktree (Step 6) and force-delete the branch: + ```bash git branch -D ``` -### Step 6: Cleanup Workspace +## Step 6: Cleanup Workspace -**Only runs for Option 1 and confirmed discards.** Options 2 and 3 always preserve the worktree. +**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) @@ -181,7 +164,9 @@ WORKTREE_PATH=$(git rev-parse --show-toplevel) **If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done. -**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup. +**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers +created this worktree — we own cleanup. Run it from the main repo root +(removal fails from inside the worktree being removed): ```bash MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) @@ -190,7 +175,8 @@ git worktree remove "$WORKTREE_PATH" git worktree prune # Self-healing: clean up any stale registrations ``` -**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place. +**Otherwise:** The host environment owns this workspace — leave it in +place. If your platform provides a workspace-exit tool, use it. ## Quick Reference @@ -201,57 +187,16 @@ git worktree prune # Self-healing: clean up any stale registrations | 3. Keep as-is | - | - | yes | - | | Discard (explicit request only) | - | - | - | yes (force) | -## Common Mistakes +## Common Rationalizations -**Skipping test verification** -- **Problem:** Merge broken code, create failing PR -- **Fix:** Always verify tests before offering options - -**Open-ended questions** -- **Problem:** "What should I do next?" is ambiguous -- **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 Option 1 and confirmed discards - -**Deleting branch before removing worktree** -- **Problem:** `git branch -d` fails because worktree still references the branch -- **Fix:** Merge first, remove worktree, then delete branch - -**Running git worktree remove from inside the worktree** -- **Problem:** Command fails silently when CWD is inside the worktree being removed -- **Fix:** Always `cd` to main repo root before `git worktree remove` - -**Cleaning up harness-owned worktrees** -- **Problem:** Removing a worktree the harness created causes phantom state -- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/` - -**No confirmation for discard** -- **Problem:** Accidentally delete work -- **Fix:** Require typed "discard" confirmation - -## Red Flags - -**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 -- Clean up worktrees you didn't create (provenance check) -- Run `git worktree remove` from inside the worktree - -**Always:** -- Verify tests before offering options -- Detect environment before presenting menu -- 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 +| Excuse | Reality | +|--------|---------| +| "Tests passed earlier this session" | Run the suite now. The tree changed since the last green run. | +| "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. | +| "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. | +| "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. | +| "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. | +| "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. | +| "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. | +| "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. | +| "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. |