From f146752b8d42ff2fe14c23ce62daf22b95873a4e Mon Sep 17 00:00:00 2001
From: Drew Ritter <drewritter@workerbee.local>
Date: Mon, 23 Mar 2026 14:26:30 -0700
Subject: [PATCH] fix(finishing-skill): move environment detection before test
 verification (PRI-823)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Path A (detached HEAD in externally managed worktree) was unreachable
because Step 1 halted on test failure before Step 1.5 could detect the
restricted environment. Reorder so detection runs first — Path A now
skips test verification entirely since the toolchain may not be available
in sandbox environments.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../finishing-a-development-branch/SKILL.md   | 72 ++++++++++---------
 1 file changed, 38 insertions(+), 34 deletions(-)

diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md
index e92ed9e8..b8e3661a 100644
--- a/skills/finishing-a-development-branch/SKILL.md
+++ b/skills/finishing-a-development-branch/SKILL.md
@@ -15,29 +15,9 @@ Guide completion of development work by presenting clear options and handling ch
 
 ## The Process
 
-### Step 1: Verify Tests
+### Step 1: Detect Environment
 
-**Before presenting options, verify tests pass:**
-
-```bash
-# Run project's test suite
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:**
-```
-Tests failing (<N> 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.
-
-### Step 1.5: Detect Environment
+Run this FIRST, before test verification:
 
 ````bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
@@ -47,12 +27,14 @@ BRANCH=$(git branch --show-current)
 
 **Path A — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` is empty (externally managed worktree, detached HEAD):**
 
-First, ensure all work is staged and committed (`git add` + `git commit`).
+This is a restricted sandbox environment (e.g., Codex App worktree thread). The test toolchain may not be available. Do NOT attempt test verification — skip directly to the handoff.
+
+First, ensure all work is staged and committed (`git add` + `git commit`). If staging/committing fails due to sandbox restrictions, note the uncommitted files in the handoff message.
 
 Then present this to the user (do NOT present the 4-option menu):
 
 ```
-Implementation complete. All tests passing.
+Implementation complete.
 Current HEAD: <full-commit-sha>
 
 This workspace is externally managed (detached HEAD).
@@ -71,17 +53,39 @@ Suggested commit message: <summary-of-work>
 
 Branch name: use ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit. Avoid sensitive content in branch names.
 
-Skip to Step 5 (cleanup is a no-op — see guard below).
+Skip to Step 6 (cleanup is a no-op — see guard below).
 
 **Path B — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` exists (externally managed worktree, named branch):**
 
-Proceed to Step 2 and present the 4-option menu as normal.
+Proceed to Step 2 (verify tests, then 4-option menu).
 
 **Path C — `GIT_DIR` equals `GIT_COMMON` (normal environment):**
 
-Proceed to Step 2 and present the 4-option menu as normal.
+Proceed to Step 2 (verify tests, then 4-option menu).
 
-### Step 2: Determine Base Branch
+### Step 2: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 3.
+
+**If tests pass:** Continue to Step 3.
+
+### Step 3: Determine Base Branch
 
 ```bash
 # Try common base branches
@@ -90,7 +94,7 @@ 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?"
 
-### Step 3: Present Options
+### Step 4: Present Options
 
 Present exactly these 4 options:
 
@@ -107,7 +111,7 @@ Which option?
 
 **Don't add explanation** - keep options concise.
 
-### Step 4: Execute Choice
+### Step 5: Execute Choice
 
 #### Option 1: Merge Locally
 
@@ -128,7 +132,7 @@ git merge <feature-branch>
 git branch -d <feature-branch>
 ```
 
-Then: Cleanup worktree (Step 5)
+Then: Cleanup worktree (Step 6)
 
 #### Option 2: Push and Create PR
 
@@ -147,7 +151,7 @@ EOF
 )"
 ```
 
-Then: Cleanup worktree (Step 5)
+Then: Cleanup worktree (Step 6)
 
 #### Option 3: Keep As-Is
 
@@ -175,9 +179,9 @@ git checkout <base-branch>
 git branch -D <feature-branch>
 ```
 
-Then: Cleanup worktree (Step 5)
+Then: Cleanup worktree (Step 6)
 
-### Step 5: Cleanup Worktree
+### Step 6: Cleanup Worktree
 
 **First, check if worktree is externally managed:**