Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/11-James-Traina-compound-science/skills/workflows-work

workflows:work

Verified

Execute research implementation plans efficiently while maintaining estimation quality and finishing features

FileKindSize
SKILL.mdskill md15.4 KB
references/worktree-patterns.mdmarkdown4.8 KB
scripts/worktree-manager.shexecutablescript8.6 KB

references/worktree-patterns.md

View on GitHub
# Git Worktree Patterns for Parallel Research Work

Manages Git worktrees for isolated parallel research work -- running concurrent estimation specifications, comparing identification strategies side-by-side, or isolating experimental numerical code.

## When to Use Worktrees

- Running multiple long-running estimation specifications in parallel (NFXP vs MPEC vs CCP)
- Comparing identification strategies side-by-side
- Isolating risky numerical experiments from working results
- Running multiple robustness specifications simultaneously
- Concurrent Monte Carlo simulations with different DGP variants

**Default to a new branch** for sequential single-branch work. Use a worktree only when true parallelism is needed.

## Using the Manager Script

**NEVER call `git worktree add` directly.** Always use the `worktree-manager.sh` script.

The script handles critical setup that raw git commands don't:
1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo
2. Ensures `.worktrees` is in `.gitignore`
3. Creates consistent directory structure

```bash
# CORRECT - Always use the script
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create nfxp-starting-values

# WRONG - Never do this directly
git worktree add .worktrees/nfxp-starting-values -b nfxp-starting-values main
```

## Commands

| Command | Description |
|---------|-------------|
| `create <branch-name> [from-branch]` | Create new worktree (copies .env files automatically; from-branch defaults to main) |
| `list` / `ls` | List all worktrees with status |
| `switch` / `go <name>` | Switch to an existing worktree |
| `copy-env` / `env [name]` | Copy .env files from main repo to worktree |
| `cleanup` / `clean` | Interactively clean up inactive worktrees |

## Directory Structure

```
.worktrees/
+-- blp-nfxp/               # NFXP estimation run
+-- blp-mpec/               # MPEC estimation run
+-- did-staggered-robust/   # Robustness specification
.gitignore (updated to include .worktrees)
```

## Workflow Examples

### Comparing Estimation Methods

```bash
# Run BLP with NFXP:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create blp-nfxp

# In parallel, run MPEC:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create blp-mpec

# And CCP:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create blp-ccp

# List all concurrent runs:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh list

# Switch to check convergence:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh switch blp-nfxp

# After comparing, clean up:
cd .
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh cleanup
```

### Parallel Robustness Specifications

```bash
# Baseline DiD with staggered adoption:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create did-staggered-robust

# Callaway-Sant'Anna:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create did-callaway-santanna

# Sun-Abraham:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create did-sun-abraham
```

### Concurrent Monte Carlo Simulations

```bash
# Baseline DGP with homoskedastic errors:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create mc-dgp-homoskedastic

# Variant with heteroskedastic errors:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create mc-dgp-heteroskedastic

# Variant with weak instruments:
bash ${CLAUDE_PLUGIN_ROOT}/skills/workflows-work/scripts/worktree-manager.sh create mc-dgp-weak-iv
```

## Key Design Principles

- **One manager script** handles all worktree operations
- Worktrees always created from **main** (unless specified)
- Worktrees stored in **.worktrees/** directory
- Branch name becomes worktree name
- **.gitignore** automatically managed
- **Won't remove the current worktree** (safety)
- Worktrees are lightweight (file system links, shared git objects)

## Troubleshooting

| Issue | Fix |
|-------|-----|
| "Worktree already exists" | Script asks if you want to switch to it instead |
| "Cannot remove worktree: it is the current worktree" | Switch out first: `cd $(git rev-parse --show-toplevel)` then cleanup |
| .env files missing in worktree | Run `bash .../worktree-manager.sh copy-env <name>` |
| Lost in a worktree? | Run `bash .../worktree-manager.sh list` |

## Integration with /workflows:work

Use a worktree when the plan involves parallel workstreams or the user has multiple active branches. Default to a new branch on the current worktree for sequential work.

```
- Parallel specs (NFXP vs MPEC, multiple robustness runs) -> worktree
- Sequential single-branch work -> create new branch normally
```

The `workflow-coordinator` agent can help decide when parallel worktrees are appropriate versus sequential work.
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall