| name | derive-experiment |
| description | 从已有实验版本派生下一版, 保证单变量隔离 + 血缘记录。Triggers when user mentions deriving a new experiment version, bumping a config, single-variable ablation, or starting next iteration based on previous. |
| user-invocable | true |
| allowed-tools | Read, Write, Edit, Bash, Glob |
Derive Experiment
派生流程的抽象, 不绑定具体工具栈。
输入
parent: 已有版本标识child: 目标版本标识change_spec: 单变量描述, 维度 ∈ {data, hyperparams, architecture}
通用流程
1. 克隆配置
复制 parent 的所有 config artifact 到 child 命名空间, 仅替换版本标识符。
2. 应用 change_spec
仅对声明的变量维度做改动:
- data 维度: 更新 manifest / split / removal-list
- hyperparams 维度: 仅改特定字段, 其他保留
- architecture 维度: 模型定义文件改
3. Diff 校验 (强制)
对每个 config 跑 diff vs parent:
- 命中 change_spec 维度的字段 → 允许
- 命中其他维度的字段 → 报错停止, 提示混入隐性变量
这是单变量原则的执行点。
4. 派生 derived artifacts
重新生成依赖于变更维度的下游产物:
- data 改 → normalization stats / cache 重算
- hyperparams 改 → 无需重算 data 产物
- architecture 改 → checkpoint 不兼容, 从头训
5. 写 lineage
调用 data-lineage skill 写 child 的 lineage.json:
- parent / derivation.method / diff_summary
- delta (removed/added if data 维度)
- verified.* 设置初始状态
6. 验证
- diff_is_single_variable: 步 3 通过
- manifest_math_consistent: child manifest == parent ± delta
- 子目录 / artifact 数量与 manifest 一致
- isolation 不变量保持 (test ∩ train = ∅ 等)
每项通过后 update lineage.json 对应 verified.* = true。
7. 输出报告
# <child> derived from <parent>
- Single variable: <dimension> / <diff_summary>
- Delta: +<added> / -<removed>
- Artifacts: <list>
- Lineage: _provenance/lineage.json
- Launch: <command>
反模式
- 跳过 diff 校验 → 单变量原则被悄悄违反
- 跨多版本跳跃 (parent → grandchild) → 血缘断, 应链式派生
- 修改 parent → 派生必须只产新 artifact, 不污染原版
- 派生时同时改多维度 → 拆成多次派生
- 复用 parent 的 normalization stats → 数据变化必须重算
- 不写 lineage → 后续追溯成本极高
单变量原则
ML/实验项目核心戒律: 每次派生只改一个维度。
想同时改 N 个 → 拆 N 次派生:
parent → child_A (改维度 1) → child_B (改维度 2) → ...
这样每个数字差异都可归因到具体改动。
