SuperAPI AI Directory

experiment-handoff

General & other

View repository

Updated 10-16 02:31

About this skill

Experimental Handoff

Role

You areExperimental Handoffthe executor of. When you need to try features/run tests midway through a project:isolate a sandbox(worktree/branch/copy), write a small experiment document and hand it off to the next agent/session, and once the experiment has a conclusion,merge the verified changes back into the main project or discard them, and clean up the sandbox.

Parallel to project-handoff(Project State Handoff): this skill only handlesa single experiment's isolation and reclamation,self-contained—it does not depend on other skills' scripts or files.

When to use (mounted · user manual only /experiment-handoff)

This skillis mounted(~/.agents/skills/experiment-handoff, the user can invoke it with /experiment-handoff ), but the agent must not trigger it autonomously—it only executes when the user explicitly invokes it:

  • Trigger method: the user types /experiment-handoff(or explicitly names the skill);manual only。
  • Three manual steps: ① the user /invoke this skill ② the user manually hands the session off to another agent ③ the user manually declares the experiment finished.
  • Everything else is automatic: detect VCS, choose an isolation strategy, create the isolation, write documents/index, record the baseline, merge back to main, clean up.

Hard constraints

  1. Isolation first—experimental changesmust not pollute the main working tree; always go into a sandbox first.
  2. Conclusion-driven merge—write 结论/反馈first, then decide the merge scope (full/partial/discard); do not merge first and add the conclusion later.
  3. Rollback-capable—record the baseline (commit/snapshot hash) before merging; run verification after merging, and roll back if it fails.
  4. Must clean up—on wrap-up, always delete the sandbox (worktree/branch/copy) and temporary branches; leave no residue.
  5. Anti-bloat—experiment documents are small (≤~600 tokens); migrate on wrap-up archive/; active experiments ≤10 (archive first if exceeded).
  6. Desensitization—documents must not contain API Keys/passwords/PII.

Isolation strategy (agent chooses automatically)

Project state Strategy Implementation
git repo,git worktree available, main tree clean worktree (default) sibling directory ../<proj>-exp-<slug> + branch exp/<slug>(not nested inside the main tree)
git repo, main tree has uncommitted changes commit/stash first → worktree worktree cannot seeuncommitted changes
git repo, small changes in place branch(--mode branch) switch directly to exp/<slug>
no git / no commit (unborn HEAD) copy copy to ../<proj>-exp-<slug>, exclude node_modules/dist/.venv/target/.next/.git; record snapshot hash
sandbox on external drive/may be unmounted git worktree lock prevent accidental prune

worktree independent dependencies each(no node_modules)—install is required after creation (pnpm shared store can save this).

Handoff document

  • Location:<项目>/.experiments/<slug>.md(local private, automatically adds .gitignore); index .experiments/EXPERIMENTS.md(auto-generated, do not edit manually).
  • Fields (per spike template: Goal→Method→Evidence→Conclusions→Next Steps):
- 状态: 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(追加式:测试/指标/观察)

Workflow

【手动触发 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)

Merge back to main project (feedback-driven)

Isolation method Merge method
worktree / branch git merge --no-ff exp/<slug>(or cherry-pick); partial merge:git checkout exp/<slug> -- <paths>
copy (non-git) generate patch (script uses diff -ruN or git diff --no-index) → after review git apply -p1 / patch -p1
  • Granularity: full / partial (only verified files) / discard—determined by 结论 .
  • Rollback: the hash of the baseline before merge is the rollback anchor (git reset --hard <base> / git revert); for copy-based, the original copy still exists and can be redone.
  • Trace: after success, leave one line per project handoff convention reference(commit/patch path;project-handoff maintained), do not copy content.

Anti-bloat

  • Closing means mv to .experiments/archive/; the index automatically distinguishes active/archived.
  • Active experiments >10 → list alert, archive/close old ones first.
  • Keep documents small; put large evidence into project docs (just reference it).

Bundled scripts

Script Platform Description
scripts/experiment.sh Linux / macOS / WSL / Git Bash init(create isolation + docs) / close(merge + cleanup + archive) / list
scripts/experiment.ps1 Windows PowerShell 5.1+(UTF-8 with BOM) same behavior; parameters are positional (-File under --x will be treated as a parameter name)

Zero python/node dependencies (bash uses coreutils+git+tar; PS uses built-ins + git/tar). Usage:

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
experiment.ps1 init  <slug> [title] [mode] [base]
experiment.ps1 close <slug> keep|discard [paths]
experiment.ps1 list  [write]

Anti-patterns

  • Experiment changes go directly into the main working tree (no isolation) → pollutes the mainline
  • Merge first, then add conclusions (no feedback basis)
  • Do not record baseline before merge (cannot roll back)
  • Closing does not clean up sandbox/branch (residual bloat)
  • Experiment docs written as a giant encyclopedia (over budget, not archived)
  • agent Autonomous invocationthis skill (should wait for user /experiment-handoff)
  • Depends on scripts/files of other skills(this skill must be self-contained)

Completion criteria

  • sandbox created and main tree not polluted (one of worktree/branch/copy)
  • explicitly triggered by user /experiment-handoff (not autonomously invoked by agent)
  • .experiments/<slug>.md exists (including Goal/Method/baseline/conclusions/merge plan/merge result/cleanup)
  • index .experiments/EXPERIMENTS.md generated
  • closing: merge or discard per conclusions; after merge, verify + reference one line per project handoff convention
  • sandbox/branch cleaned up; docs migrated archive/
  • no sensitive information

Methodology sources (2026-09 research)

  • Technical Spike template(Microsoft Engineering Playbook): Goal / Method / Evidence / Conclusions / Next Steps—source of this skill's document fields
  • Git worktree best practices(GitWorktree.org): sibling directory layout,<project>-<branch-slug> naming, after merge git worktree remove + prune, each worktree has independent dependencies — source of the isolation strategy
  • Agent handoff pattern(Microsoft Agent Framework / AutoGen): explicitly hand over control — source of the manual three-stage trigger model