From 998c40be299d1bcf5fd1700a4319a4e1f0d60f54 Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Mon, 13 Apr 2026 11:43:45 -0700 Subject: [PATCH] docs: soften Step 1a native-tool framing per PR #1121 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address obra's comment on explicit step numbers / prescriptive tone. Drops "STOP HERE if available", the "If YES:" gate, and the "even if / even if / NO EXCEPTIONS" reinforcement paragraph. Keeps the specific tool-name anchors (EnterWorktree, WorktreeCreate, /worktree, --worktree), which the original TDD data showed are load-bearing. A/B verified against drill harness on the 3 creation/consent scenarios (consent-flow, creation-from-main, creation-from-main-spec-aware): baseline explicit wording scored 12/12 criteria, softened wording also scored 12/12. The "agent used the most appropriate tool" criterion passed in all 3 softened runs — agents still picked EnterWorktree via ToolSearch without the imperative framing. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/using-git-worktrees/SKILL.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index 54ca440a..66dcbdac 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/skills/using-git-worktrees/SKILL.md @@ -48,15 +48,13 @@ Honor any existing declared preference without asking. If the user declines cons **You have two mechanisms. Try them in this order.** -### 1a. Native Worktree Tools (preferred — STOP HERE if available) +### 1a. Native Worktree Tools (preferred) -The user has asked for an isolated workspace (Step 0 consent). Check your available tools — do you have `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag? **If YES: the user's consent to create a worktree is your authorization to use it. Use it now and skip to Step 3.** +The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3. -Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state — your harness can't see or manage worktrees it didn't create, and cleanup becomes impossible. +Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage. -**Even if `.worktrees/` already exists, even under time pressure, even if `git worktree add` feels faster — use your native tool.** There are no exceptions. - -**Only proceed to Step 1b if you have confirmed you have NO native worktree/isolation tool.** +Only proceed to Step 1b if you have no native worktree tool available. ### 1b. Git Worktree Fallback