Sfoglia il codice sorgente

fix: invert worktree skill default to work-in-place, eliminating Step 0.5 (PRI-974)

Agents consistently skipped Step 0.5 (consent gate) because fractional
numbering signals "optional afterthought" and the prose-only step was
invisible to code-block anchoring. The fix inverts the structural
gravity: the default path now works in place, and worktree creation
is an off-ramp requiring explicit user request.

- Renumber to clean integers: Step 1 (detect) → 2 (offer) → 3 (create) → 4 (setup) → 5 (verify)
- Step 2 defaults to Step 4 (in-place); Step 3 only on explicit user ask
- Step 2 includes a code block so agents register it during execution
- Add "creating without being asked" to Common Mistakes
- Add anti-inference red flag: consent from task/plan/skill invocation doesn't count

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Drew Ritter 5 mesi fa
parent
commit
7c4597af34
1 ha cambiato i file con 65 aggiunte e 34 eliminazioni
  1. 65 34
      skills/using-git-worktrees/SKILL.md

+ 65 - 34
skills/using-git-worktrees/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - detects environment, offers worktree isolation when appropriate
 ---
 
 # Using Git Worktrees
 
 ## Overview
 
-Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+Detect the workspace environment. Work in place by default. Offer worktree isolation when the user would benefit, but only create one when they explicitly ask.
 
-**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+**Core principle:** Detect first. Default to working in place. Create worktrees only on explicit user request. Never fight the harness.
 
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+**Announce at start:** "I'm using the using-git-worktrees skill to check the workspace."
 
-## Step 0: Detect Existing Isolation
+## Step 1: Detect Existing Isolation
 
-**Before creating anything, check if you are already in an isolated workspace.**
+**Before anything else, check if you are already in an isolated workspace.**
 
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
@@ -30,42 +30,53 @@ BRANCH=$(git branch --show-current)
 git rev-parse --show-superproject-working-tree 2>/dev/null
 ```
 
-**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 4 (Project Setup). Do NOT create another worktree.
 
 Report with branch state:
 - On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
 - Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
 
-**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Proceed to Step 0.5.
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Proceed to Step 2.
 
-## Step 0.5: Consent — REQUIRED STOP
+## Step 2: Offer Workspace Options
 
-**You MUST ask the user before creating any workspace. Do NOT proceed to Step 1 without an answer.**
+**The default path is to work in place on your current branch.** Do NOT create a worktree unless the user explicitly asks for one.
 
-Output exactly this, then STOP and wait for a response:
+```bash
+# Report current state to the user
+echo "Current branch: $BRANCH"
+echo "Repository: $(basename "$(git rev-parse --show-toplevel)")"
+```
+
+Tell the user their options, then **wait for a reply**:
 
-> "I can set up an isolated worktree for this work, or work directly on your current branch. Which do you prefer?"
+> "You're on `<branch>` in `<repo>`. I can set up an isolated worktree, or we can work directly here. What do you prefer?"
 
-- **User wants a worktree** → proceed to Step 1
-- **User wants to work in place** → skip to Step 3 (no worktree, no directory change)
+**Routing:**
+- **User explicitly asks for a worktree** → proceed to Step 3
+- **User says work in place** → skip to Step 4
+- **User gives no clear worktree preference** → skip to Step 4 (default is in-place)
+- **Silence or unrelated reply** → skip to Step 4 (default is in-place)
 
-Do NOT interpret silence or an unrelated reply as consent. If unclear, ask once more.
+The default is always Step 4. Step 3 requires an explicit "yes, create a worktree" from the user.
 
-## Step 1: Create Isolated Workspace
+## Step 3: Create Worktree
 
-**You have two mechanisms. Try them in this order.**
+**You only reach this step because the user explicitly asked for a worktree in Step 2.**
 
-### 1a. Native Worktree Tools (preferred)
+You have two mechanisms. Try them in this order.
 
-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.
+### 3a. Native Worktree Tools (preferred)
+
+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 4.
 
 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.
 
-Only proceed to Step 1b if you have no native worktree tool available.
+Only proceed to Step 3b if you have no native worktree tool available.
 
-### 1b. Git Worktree Fallback
+### 3b. Git Worktree Fallback
 
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+**Only use this if Step 3a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
 
 #### Directory Selection
 
@@ -118,7 +129,7 @@ cd "$path"
 
 **Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
 
-## Step 3: Project Setup
+## Step 4: Project Setup
 
 Auto-detect and run appropriate setup:
 
@@ -137,7 +148,7 @@ if [ -f pyproject.toml ]; then poetry install; fi
 if [ -f go.mod ]; then go mod download; fi
 ```
 
-## Step 4: Verify Clean Baseline
+## Step 5: Verify Clean Baseline
 
 Run tests to ensure workspace starts clean:
 
@@ -152,20 +163,30 @@ npm test / cargo test / pytest / go test ./...
 
 ### Report
 
+If working in a worktree:
 ```
 Worktree ready at <full-path>
 Tests passing (<N> tests, 0 failures)
 Ready to implement <feature-name>
 ```
 
+If working in place:
+```
+Working in place on <branch> at <path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
 ## Quick Reference
 
 | Situation | Action |
 |-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
+| Already in linked worktree | Skip creation, go to Step 4 (Step 1) |
+| In a submodule | Treat as normal repo (Step 1 guard) |
+| Normal repo, user wants in-place | Work in place, go to Step 4 (Step 2 default) |
+| Normal repo, user asks for worktree | Create worktree (Step 3) |
+| Native worktree tool available | Use it (Step 3a) |
+| No native tool | Git worktree fallback (Step 3b) |
 | `.worktrees/` exists | Use it (verify ignored) |
 | `worktrees/` exists | Use it (verify ignored) |
 | Both exist | Use `.worktrees/` |
@@ -175,19 +196,25 @@ Ready to implement <feature-name>
 | Permission error on create | Sandbox fallback, work in place |
 | Tests fail during baseline | Report failures + ask |
 | No package.json/Cargo.toml | Skip dependency install |
-| Plan touches multiple repos | Create a matching worktree in each repo, same branch name |
+| User gives no worktree preference | Work in place (Step 2 default) |
+| Plan touches multiple repos | Offer a matching worktree per repo, same branch name |
 
 ## Common Mistakes
 
+### Creating a worktree without being asked
+
+- **Problem:** Agent creates a worktree because the skill was invoked, without the user requesting one
+- **Fix:** Step 2 defaults to working in place. Only Step 3 creates, and only after explicit user request.
+
 ### Fighting the harness
 
 - **Problem:** Using `git worktree add` when the platform already provides isolation
-- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+- **Fix:** Step 1 detects existing isolation. Step 3a defers to native tools.
 
 ### Skipping detection
 
 - **Problem:** Creating a nested worktree inside an existing one
-- **Fix:** Always run Step 0 before creating anything
+- **Fix:** Always run Step 1 before creating anything
 
 ### Skipping ignore verification
 
@@ -207,15 +234,19 @@ Ready to implement <feature-name>
 ## Red Flags
 
 **Never:**
-- Create a worktree when Step 0 detects existing isolation
+- Create a worktree without the user explicitly asking for one
+- Create a worktree when Step 1 detects existing isolation
 - Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
-- Skip Step 1a by jumping straight to Step 1b's git commands
+- Skip Step 3a by jumping straight to Step 3b's git commands
 - Create worktree without verifying it's ignored (project-local)
 - Skip baseline test verification
 - Proceed with failing tests without asking
+- Infer worktree consent from the task description, plan, or skill invocation — only an explicit user reply counts
 
 **Always:**
-- Run Step 0 detection first
+- Run Step 1 detection first
+- Default to working in place (Step 2 → Step 4)
+- Only create a worktree after explicit user request
 - Prefer native tools over git fallback
 - Follow directory priority: existing > global legacy > instruction file > default
 - Verify directory is ignored for project-local