derive-experiment

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) → ...

这样每个数字差异都可归因到具体改动。