v1.0.4 to v1.1.0

---

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

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/`

- [ ] 无敏感信息

## 方法论来源（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）：显式交接控制权——手动三段触发模型来源