experiment-worktree

Experiment Worktree

Create an isolated git worktree before making experiment-specific code changes. This ensures failed or inconclusive experiments can be discarded without touching the main branch.

Announce at start: "I'm using the experiment-worktree skill to set up an isolated workspace."

When To Use

• Called by experiment-execution step 2, before any code changes.
• Called directly when the user wants to isolate DL work on a separate branch.
• Skip if the user explicitly opts out of worktree isolation.

Directory Setup

Run directory setup from the main project root, not from an existing worktree. For this skill:

• <project_root> means the original checkout where the user started.
• <worktree_path> means <project_root>/.worktrees/<topic>.
• Any .worktrees/<topic>/... path is relative to <project_root> unless the step explicitly says to run inside the worktree.

1. Check for .worktrees/

ls -d .worktrees 2>/dev/null

If found, use it. If not found, create it.

2. Verify Gitignored

git check-ignore -q .worktrees

If NOT ignored: add .worktrees/ to .gitignore, commit the change, then proceed.

Branch Naming

Default pattern: exp/<YYYY-MM-DD>-<topic>

• <topic> comes from the experiment plan filename or the hypothesis summary.
• Must match the experiment note naming convention used by experiment-design and experiment-closeout (i.e., YYYY-MM-DD-<topic>).
• Example: exp/2026-04-11-rotary-embeddings

If the user provides a branch name, use it as-is.

Creation Steps

1. Determine the branch name from the experiment plan or ask the user.
2. From <project_root>, record pre-worktree state:
   • current branch (git branch --show-current)
   • current commit (git rev-parse HEAD)
   • working tree clean status (git status --porcelain)
3. From <project_root>, create the worktree:

   git worktree add .worktrees/<topic> -b exp/<YYYY-MM-DD>-<topic>
   

4. From <project_root>, create dataset symlinks into <worktree_path> if needed (see below).
5. Change into <worktree_path>.
6. Run DL environment setup (see below).
7. Run sanity verification (see below).
8. Write start-state metadata to <worktree_path>/.experiment-metadata.json.
9. Report readiness.

DL Environment Setup

Auto-detect and run the appropriate setup in priority order:

1. pyproject.toml with [tool.poetry] -> poetry install
2. pyproject.toml without poetry -> pip install -e .
3. setup.py or setup.cfg -> pip install -e .
4. requirements.txt -> pip install -r requirements.txt
5. environment.yml -> conda env update

After dependency setup:

• Check CUDA availability: python -c "import torch; print(torch.cuda.is_available())" (skip if torch is not installed).

Dataset Symlink

Large datasets must never be copied into the worktree. Instead, create symbolic links pointing back to the original project directory so every worktree shares the same data on disk.

Detection — scan the main project root (not the worktree) for data directories in priority order:

1. Paths listed in config files (.env, config.yaml, *.toml [data] sections, etc.).
2. Common convention directories: data/, datasets/, raw_data/, processed_data/.
3. Any top-level directory that is gitignored and larger than 100 MB.

Creation — for every detected data directory <dir>:

# Run from <project_root>, or use absolute paths.
ln -s <resolved_data_path> <worktree_path>/<dir>

• If <dir> already exists in the worktree (because it is tracked), skip it and warn.
• If <dir> is itself a symlink in the main project, resolve it first (readlink -f) and link to the resolved target.
• After linking, verify the symlink is accessible: ls <linked_path> > /dev/null.

Record — add a "symlinked_data" array to .experiment-metadata.json listing every path that was symlinked, so finishing-experiment-branch knows not to delete real data during cleanup.

If no data directories are found, report that no dataset symlinks were created and ask whether the experiment needs data that should be linked manually.

Sanity Verification

• Run pytest or the project-specific test command if a test suite exists.
• If tests fail, report failures and ask whether to proceed.
• If no tests exist, report that baseline verification was skipped.

Start-State Metadata

Write <worktree_path>/.experiment-metadata.json so that a future session can detect and resume:

{
  "worktree_path": ".worktrees/<topic>",
  "branch_name": "exp/<YYYY-MM-DD>-<topic>",
  "base_branch": "main",
  "base_commit": "<hash>",
  "tree_was_clean": true,
  "environment_tool": "pip",
  "symlinked_data": ["data/", "datasets/raw"],
  "created_at": "<ISO-8601>"
}

Report

Worktree ready at .worktrees/<topic>
Branch: exp/<YYYY-MM-DD>-<topic>
Base commit: <hash>
Environment: <pip/poetry/conda>
CUDA: <available/not available/not checked>
Tests: <N passing / skipped>

Guardrails

• Never create a worktree without verifying .worktrees/ is gitignored.
• Never skip environment setup — a worktree with mismatched dependencies produces false failures.
• Never proceed with failing CUDA checks if the experiment requires GPU.
• Never mix unrelated code changes into the experiment branch.

Integration

Called by: experiment-execution (step 2)

Pairs with: finishing-experiment-branch (cleanup after experiment)