Experiment Handoff

---
name: experiment-handoff
description: >-
  Experiment handoff for mid-project experiments and spikes. Isolates a trial in a git worktree
  (default), an in-place branch, or a project copy; records a small experiment doc
  (.experiments/<slug>.md plus a generated index); supports handing off to another agent/session;
  and on close merges the validated change back into the project (full or partial) or discards it,
  then cleans up the sandbox. Auto-detects VCS and the isolation strategy, and records the base
  revision. This skill is mounted but USER-INVOKED ONLY: the agent must NOT auto-invoke it — the
  user runs it explicitly as /experiment-handoff. Use when the user explicitly invokes
  /experiment-handoff to start, hand off, or close an experiment/spike. NOT for: the
  project-wide handoff store or resuming prior work on a project.
slug: experiment-handoff
version: 1.1.0
displayName: experiment-handoff
disable-model-invocation: true
---

# 实验性交接（Experiment Handoff）

## 角色

你是**实验性交接**的执行者。项目进行到中途要试功能/跑测试时：**隔离出一个沙箱**（worktree/branch/copy），写一份小实验文档交接给下一个 agent/session，实验有结论后**把验证过的改动合并回主项目或丢弃**，并清理沙箱。

与 `project-handoff`（项目状态交接）并列：本技能只管**单个实验**的隔离与回收，**自足**——不依赖其它技能的脚本或文件。

## 何时使用（**已挂载 · 仅用户手动 `/experiment-handoff`**）

本技能**已挂载**（`~/.agents/skills/experiment-handoff`，用户可用 `/experiment-handoff` 调用），但 **agent 不得自主触发**——只有用户显式调用时才执行：

- **触发方式**：用户键入 `/experiment-handoff`（或明确点名该技能）；**仅手动**。
- 三段手动：① 用户 `/invoke` 本技能 ② 用户手动把会话交给另一个 agent ③ 用户手动宣告实验结束。
- **其余全自动**：探测 VCS、选隔离策略、建隔离、写文档/索引、记基线、合并回主、清理。

## 硬约束

1. **隔离优先**——实验改动**不得污染主工作树**；一律先进沙箱。
2. **结论驱动合并**——先写 `结论/反馈`，再决定合并范围（全量/部分/丢弃）；不得先合并后补结论。
3. **可回滚**——合并前记基线（commit/快照 hash）；合并后跑验证，不通过即回滚。
4. **必清理**——收束必删沙箱（worktree/branch/copy）与临时分支；不留残留。
5. **防膨胀**——实验文档小（≤~600 tokens）；收束即迁 `archive/`；活跃实验 ≤10 条（超出先归档）。
6. **脱敏**——文档不含 API Key/密码/PII。

## 隔离策略（agent 自动选）

| 项目状态 | 策略 | 落地 |
|---|---|---|
| git 仓、`git worktree` 可用、主树干净 | **worktree（默认）** | **兄弟目录** `../<proj>-exp-<slug>` + 分支 `exp/<slug>`（不嵌在主树内）|
| git 仓、主树有未提交改动 | 先 commit/stash → worktree | worktree **看不到**未提交改动 |
| git 仓、小改动就地 | **branch**（`--mode branch`）| 直接切 `exp/<slug>` |
| 无 git / 无 commit（unborn HEAD）| **copy** | 复制到 `../<proj>-exp-<slug>`，排除 `node_modules/dist/.venv/target/.next/.git`；记快照 hash |
| 沙箱在外置盘/可能卸载 | `git worktree lock` | 防误 prune |

worktree **各自独立依赖**（无 `node_modules`）——建后需 install（pnpm 共享 store 可省）。

## 交接文档

- 位置：`<项目>/.experiments/<slug>.md`（本地私有，自动加 `.gitignore`）；索引 `.experiments/EXPERIMENTS.md`（**自动生成**，勿手改）。
- 字段（按 spike 模板：Goal→Method→Evidence→Conclusions→Next Steps）：

```markdown
- 状态: open | running | concluded | promoted | discarded
- 日期 / 标题
- Goal: 一句话问题/假设
- Method: 方法
- 隔离: <worktree|branch|copy> · 位置: <path> · 分支: <exp/slug 或 ->
- 基线: <commit 短 hash 或 copy 快照 hash>
- Run: 命令
- 结论: <反馈——合并依据>
- Next Steps:
- 合并计划: 全量 | 部分(<paths>) | 丢弃
- 合并结果: <merge commit / patch 文件 / 未合并>
- 清理: <命令>
## Evidence（追加式：测试/指标/观察）
```

## 工作流

```
【手动触发 1】开
- [ ] 1. 探测：git 仓？worktree 可用？主树干净？（无 git → copy）
- [ ] 2. 选隔离策略（见上表），建沙箱（worktree/branch/copy）
- [ ] 3. 写 .experiments/<slug>.md（含基线）+ 生成索引
- [ ] 4. （worktree）cd 沙箱 && install 依赖

【手动触发 2】续 / 交办
- [ ] 5. 读文档 → 若文档里的基线 commit 已前进，先确认是否需要重取基线 / 重新隔离
- [ ] 6. 进沙箱继续实验，Evidence 追加

【手动触发 3】收
- [ ] 7. 填 结论/反馈 → 定合并计划（全量/部分/丢弃）
- [ ] 8. 合并回主：git 系 `merge`/`cherry-pick`（部分用 `git checkout exp/<slug> -- <paths>`）；copy 系生成补丁后应用
- [ ] 9. 合并后：跑测试 → 按项目交接约定留一行引用（`project-handoff`；不复制）
- [ ] 10. 清理沙箱 + 归档文档（状态 promoted/discarded）
```

## 合并回主项目（反馈驱动）

| 隔离方式 | 合并手段 |
|---|---|
| worktree / branch | `git merge --no-ff exp/<slug>`（或 `cherry-pick`）；部分合并：`git checkout exp/<slug> -- <paths>` |
| copy（非 git）| 生成补丁（脚本用 `diff -ruN` 或 `git diff --no-index`）→ 审阅后 `git apply -p1` / `patch -p1` |

- **粒度**：全量 / 部分（只带验证过的文件）/ 丢弃——由 `结论` 决定。
- **回滚**：合并前基线的 hash 是回滚锚点（`git reset --hard <base>` / `git revert`）；copy 系原副本仍在，可重来。
- **落痕**：成功后按项目交接约定留一行 **引用**（commit/补丁路径；`project-handoff` 维护），不复制内容。

## 防膨胀

- 收束即 `mv` 到 `.experiments/archive/`；索引自动区分 active/archived。
- 活跃实验 >10 → `list` 告警，先归档/收束旧的。
- 文档保持小；大段证据进项目 docs（引用即可）。

## 附带脚本

| 脚本 | 平台 | 说明 |
|------|------|------|
| `scripts/experiment.sh` | Linux / macOS / WSL / Git Bash | `init`（建隔离+文档）/ `close`（合并+清理+归档）/ `list` |
| `scripts/experiment.ps1` | Windows PowerShell 5.1+（UTF-8 **带 BOM**）| 同行为；参数为位置式（`-File` 下 `--x` 会被当参数名）|

零 python/node 依赖（bash 用 coreutils+git+tar；PS 用内建 + git/tar）。用法：

```bash
scripts/experiment.sh init <slug> [--title T] [--mode worktree|branch|copy] [--base REF]
scripts/experiment.sh close <slug> --keep|--discard [--paths p1,p2]
scripts/experiment.sh list
```
```powershell
experiment.ps1 init  <slug> [title] [mode] [base]
experiment.ps1 close <slug> keep|discard [paths]
experiment.ps1 list  [write]
```

## 反模式

- 实验改动直接落主工作树（无隔离）→ 污染主线
- 先合并后补结论（无反馈依据）
- 合并前不记基线（无法回滚）
- 收束不清理沙箱/分支（残留膨胀）
- 实验文档写成大百科（超预算、不归档）
- agent **自主调用**本技能（应等用户 `/experiment-handoff`）
- **依赖其它技能的脚本/文件**（本技能须自足）

## 完成标准

- [ ] 沙箱已建且主树未被污染（worktree/branch/copy 其一）
- [ ] 由用户 `/experiment-handoff` 显式触发（非 agent 自主调用）
- [ ] `.experiments/<slug>.md` 存在（含 Goal/Method/基线/结论/合并计划/合并结果/清理）
- [ ] 索引 `.experiments/EXPERIMENTS.md` 已生成
- [ ] 收束：按结论合并或丢弃；合并后有验证 + 按项目交接约定引用一行
- [ ] 沙箱/分支已清理；文档已迁 `archive/`
- [ ] 无敏感信息

## 常见错法 → 改法 / FAQ

| 错法 | 改法 |
| :--- | :--- |
| 直接改主工作树"就试一下" | 停手——先 `experiment.sh init <slug>`，改动进沙箱 |
| `init` 报 `exit 2`（用法错） | 核对调用形：`experiment.sh init <slug> [--title T] [--mode ...] [--base REF]`；slug 必填 |
| `init` 报 `exit 1`（执行错） | 看 stderr 首行：多为 worktree 不可用或主树未提交改动未 stash——按提示处理后重跑 |
| `close` 想只带部分文件 | 用 `--paths p1,p2`；不带则全量合并，`--discard` 则丢弃 |
| `close --keep` 后测试不过 | 回滚锚点＝文档里的基线 hash：`git reset --hard <base>`；copy 系原副本仍在，可重来 |
| 主树有未提交改动时开 worktree | 先 `git stash` 或 commit——worktree 看不到未提交改动 |
| 手改 `.experiments/EXPERIMENTS.md` | 索引是自动生成的，手改会被覆盖；改状态请改各自实验文档的 `状态:` 字段 |
| 实验做完忘了收 | `experiment.sh list` 会列出 open/running 的实验与告警（活跃 >10 条） |

**边界判定：** 无 git 仓 → 自动走 copy，无需选择；slug 与已有实验重名 → 先 `list` 查看再用新 slug，不覆盖旧文档；沙箱目录已存在 → 报错退出（exit 1），换 slug 或先清理，不静默复用。

## 方法论来源（2026-09 调研）

- **Technical Spike 模板**（Microsoft Engineering Playbook）：Goal / Method / Evidence / Conclusions / Next Steps——本技能文档字段来源
- **Git worktree 最佳实践**（GitWorktree.org）：兄弟目录布局、`<project>-<branch-slug>` 命名、合并后 `git worktree remove` + `prune`、每 worktree 独立依赖——隔离策略来源
- **Agent handoff 模式**（Microsoft Agent Framework / AutoGen）：显式交接控制权——手动三段触发模型来源