---
name: using-worktrees
description: This skill should be used when starting work that may need isolation from the current checkout — parallel to something already in progress, risky or experimental, a hotfix interrupting other work, or a task that splits into independent mergeable units. Also when the user explicitly asks for a worktree. Examples: "try this risky refactor", "I need to fix prod while keeping this branch", "explore an alternate approach", "make a worktree for X".
---

# Using Worktrees

Decide *whether* to isolate work in a git worktree, then create it correctly. The judgment — "does this need its own worktree?" — is the point of this skill; the mechanics are routine.

**Asymmetry with committing (deliberate):** when the heuristic clearly fires, **just create the worktree** — you have standing trust here. When it's ambiguous, **propose it in one line and wait**. This is unlike committing, which is always command-gated. Creating a worktree is cheap and reversible; making a commit is not, so the trust differs.

## The WHEN heuristic (the core)

### Just create (clear — no need to ask)

- Work that runs **parallel** to something already in progress (don't disturb the in-flight checkout).
- A **risky / experimental / throwaway** change you might want to discard cleanly.
- A **hotfix that interrupts** in-progress work (isolate the fix, leave the WIP untouched).
- Work that **decomposes into independent mergeable units** — one worktree per unit.
- Any task where the user would plausibly want it isolated from the main checkout.

### Propose first (ambiguous — one line, then wait)

- Could-go-either-way on size or risk.
- Unsure whether the user wants isolation at all.
- A worktree that would **overlap heavily** with the work already on the main checkout (isolation buys little, may confuse).

State it in one line: *"This looks risky/parallel — want me to do it in a worktree?"* Then wait.

### Skip (no worktree — work on the current checkout)

- Quick reads, questions about the repo, investigation.
- Small single-stream fixes with nothing to run in parallel.
- Anything where there's nothing to isolate and no parallelism to protect.

```
parallel / risky / hotfix-interrupting / decomposable  ->  just create
ambiguous size-or-risk / heavy overlap with current     ->  propose (1 line), wait
quick read / small single-stream / nothing to isolate   ->  skip, work in place
```

## The HOW (mechanics)

- **Branch from a stable base** — the default branch (main/master), never from another feature branch. A worktree off a half-done branch inherits its instability.
- **Branch name derived from the task** — `fix-session-delete-guard`, not `wip` or `tmp`. No emojis.
- **Collision-safe path** — a unique dir outside the main checkout (e.g. a per-task or per-branch path), so two worktrees never share a directory.
- **Run the project's setup after create** — install deps / env / generate, if the project defines a setup step. A fresh worktree has the code but not the installed/generated state. (Some projects declare setup hooks; run whatever the project defines — don't assume the checkout is ready to run bare.)

## Runtime isolation caveat

A worktree isolates **code state**, not **execution state**. Ports, databases, caches, lockfiles, and running services can still collide between worktrees. Don't assume a worktree means a fully isolated environment — if two worktrees both run the app, give each its own port / DB / service via per-worktree setup. Code isolation ≠ runtime isolation.

## Lifecycle

- Worktrees **persist** — they are not auto-reaped. Leaving one around is fine; it's not litter.
- **Reconcile via git**, never automatically: review the worktree's diff against its base, then merge or archive on the user's decision. Do not auto-merge.
- **Commit inside a worktree only on the user's command** — defer to the `committing-changes` skill for the commit step (same rules: present-and-stop, never push).

## DO-NOT

- **Never branch from a non-stable base** (another feature branch). Stable base only.
- **Never auto-merge or auto-reconcile** a worktree back. That's a reviewed decision.
- **Never push** (worktrees change nothing about the push rule — that stays the user's manual step).
- **Never `git worktree remove`** without the user's say. Worktrees persist; removing one can discard uncommitted work.
- **No emojis** in branch names.

## Anti-patterns this skill avoids

- Asking permission for an obviously-isolated task (clear cases: just create).
- Creating a worktree for a quick read or a one-line fix (nothing to isolate).
- Branching the worktree off the messy in-progress branch instead of the stable base.
- Assuming a worktree gives runtime isolation and then colliding on a port or DB.
- Auto-removing or auto-merging a worktree the user hasn't reconciled.
