experiment-design-planner

实验设计规划器

将研究主张转化为能够真正回答问题的实验计划。本技能用于运行实验前的规划，而非汇报已完成的结果。

在以下情况下使用本技能：

• 用户即将运行新实验或消融实验
• 论文主张需要证据支持
• 基线、指标、对照或数据集尚不明确
• 用户一次更改了太多变量
• 应避免将集群／计算时间浪费在含糊不清的运行上
• 投稿前需要经得起审稿人检验的证据

将本技能与以下技能搭配使用：

• 当实验计划需要沉淀为项目级证据、风险和行动记忆时，搭配 research-project-memory
• 设计完成、准备执行时，搭配 run-experiment
• 获得结果后，搭配 experiment-report-writer
• 使用 paper-reviewer-simulator 压力测试证据是否足以满足审稿人要求
• 当需要更深入地审查基线选择、公平性或经得起审稿人检验的比较时，在确定实验矩阵前搭配 baseline-selection-audit
• 获得绘图或制表结果后，若需审查其对主张的支持程度，搭配 figure-results-review

技能目录结构

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── ablation-matrix.md
    ├── evidence-standards.md
    ├── metrics-and-controls.md
    └── report-template.md

渐进式加载

• 始终阅读 references/evidence-standards.md 和 references/metrics-and-controls.md。
• 当计划比较变体、组件、基线、超参数、数据集或模型规模时，阅读 references/ablation-matrix.md。
• 保存或返回大量实验计划时，使用 references/report-template.md。
• 如果目标仓库有 memory/，请遵循 research-project-memory 约定，更新计划中的证据、实验系列、风险和行动。
• 如果实验依赖当前基线、基准或排行榜惯例，请通过网络搜索核实最新来源。

核心原则

• 从主张出发，而非从命令行出发。
• 运行实验前明确假设。
• 引入新方法前先使用基线。
• 除非实验明确采用析因设计，否则一次只更改一个变量。
• 在解读结果前定义对照和干扰变量。
• 通过定义证伪条件和备选决策，让负面结果也有价值。
• 在运行实验前设计表格或图表。
• 停止条件很重要：决定什么结果足以进入下一步。

步骤 1 - 定义主张和问题

提取：

• 论文或项目主张
• 研究问题
• 目标受众：内部调试、导师进展汇报、论文证据、答辩或基准主张
• 预期产出：Markdown 计划、LaTeX 实验章节大纲、运行矩阵或保存的文件
• 实验模式：
  • single：一次受控比较
  • ablation：隔离组件或变量
  • benchmark：跨数据集／任务比较方法
  • theory：为理论预测提供实证支持
  • diagnostic：理解故障模式或意外结果

将模糊目标改写为可检验的问题：

Vague: Does our method work?
Testable: Does component X improve metric M over baseline B on datasets D1/D2 under the same training budget?

步骤 2 - 明确假设

写明：

• 主要假设
• 其他可能解释
• 预期指标变化方向和大致效应量
• 证伪条件
• 决策规则

如果用户无法陈述证伪条件，实验就尚未准备就绪。

步骤 3 - 定义证据标准

阅读 references/evidence-standards.md。

确定所需证据：

• 一张表、一条曲线、一项消融、一个定性示例、一个与定理对应的诊断，或一套基准测试
• 数据集／任务数量
• 种子数或重复次数
• 必需的基线
• 可接受的方差
• 是否需要统计检验或置信区间
• 结果是必须支持论文主张，还是仅用于指导后续步骤

步骤 4 - 选择基线和对照

确定：

• 主要基线
• 相关的最强先前方法或当前 SOTA
• 简单基线
• 消融基线
• 有用时采用的预言机或上界
• 受控变量
• 干扰变量

如果没有可用基线，请将第一次实验设计为建立基线的实验。

第 5 步 - 选择指标和日志记录

阅读 references/metrics-and-controls.md。

为每项指标指定：

• 定义
• 方向
• 聚合方式
• 分组
• 方差报告方式
• 失败情况的解读
• 为什么它能回答问题

定义必需的日志记录内容：

• 命令
• 配置路径
• git 提交
• 数据集版本
• 随机种子
• 超参数
• 硬件/运行时
• 指标
• 产物：表格、图表、检查点、日志

第 6 步 - 构建运行矩阵

如果运行次数超过 1 次，请阅读 references/ablation-matrix.md。

创建一个运行表，包含：

• 运行 ID
• 变更的变量
• 固定的控制项
• 数据集/划分
• 指标
• 随机种子/重复次数
• 预期结果
• 状态
• 输出路径

如果一次运行变更了多个概念变量，请拆分实验。

第 7 步 - 定义停止条件和后续决策

写明：

• 什么结果足以支持该论断
• 什么结果会证伪或削弱该论断
• 什么结果会触发另一项消融实验
• 什么结果意味着停止并撰写报告
• 计算资源预算上限
• 截止时间限制

第 8 步 - 检查评审者风险

定稿前，先问：

• 评审者会不会认为基线过弱？
• 比较是否公平？
• 随机种子/重复次数是否足够？
• 实验是否隔离了所声称的机制？
• 指标是否与论断一致？
• 是否存在能够解释结果的混杂因素？
• 即使结果为负，是否仍有启示？

如果答案暴露出重大弱点，请在执行前更新设计。

第 9 步 - 编写实验计划

使用 references/report-template.md。

如果要保存到项目中且未提供路径，请使用：

docs/experiments/experiment_plan_YYYY-MM-DD_<short-name>.md

如果在由 init-python-project / new-workspace 创建的代码仓库或代码 worktree 中工作，请优先使用：

docs/reports/experiment_plan_YYYY-MM-DD_<short-name>.md

最终计划应可由 run-experiment 执行，之后也可由 experiment-report-writer 生成报告。

第 10 步 - 写回项目记忆

如果项目使用 research-project-memory，请更新：

• memory/evidence-board.md：计划中的 EVD-### 条目和 EXP-### 实验系列
• memory/provenance-board.md：计划中的来源类别、预期的 CSV/报告输出，以及已知的聚合要求
• memory/claim-board.md：关联论断，并如实将论断标记为 planned、evidence-needed 或 provisional
• memory/risk-board.md：设计暴露出的基线、机制、指标、随机种子、计算资源和评审者风险
• memory/action-board.md：可执行的后续操作，包括优先启动哪项实验
• memory/handoff-board.md：计划可执行时，创建交接内容并交给 run-experiment
• memory/phase-dashboard.md：更新当前的实验设计或证据产出关卡
• 相关 worktree 的 .agent/worktree-status.md：如果涉及分支/worktree，记录实验目的和退出条件

尚未运行的实验请标记为 planned 状态。不要将预期结果记录为已观察到的证据。

最终检查

定稿前，请确认：

• 论断和假设明确
• 基线已定义
• 自变量已隔离
• 已列出控制变量和干扰变量
• 指标与问题相关
• 运行矩阵具体明确
• 日志要求足以支持复现
• 停止条件和决策规则明确
• 已说明评审者风险
• 仓库包含 memory/ 时，已更新项目记忆