experiment-report-writer

实验报告撰写器

将实验依据整理成清晰的研究报告，让读者无需重新运行实验也能进行评估。

使用此技能撰写独立文档、论文或实验记录中的一个章节、供导师审阅的进展更新，或适合演示的实验摘要。

当已完成的结果应更新项目主张、依据、风险、行动、图表或工作树决策时，请将此技能与 research-project-memory 搭配使用。

技能目录结构

<installed-skill-dir>/
├── SKILL.md
└── templates/
    └── experiment-report.md

渐进式加载

• 保存报告时，默认使用 templates/experiment-report.md 作为 Markdown 骨架。
• 如果用户只想在聊天中获取草稿，则遵循相同的章节顺序，无需逐字读取或复制模板。

核心原则

• 每项主张都要有依据：配置、命令、日志、指标、表格、图表、提交哈希或用户提供的笔记。
• 将观察到的结果与解读区分开。不要把假设说成测量所得的事实。
• 确保报告具有足够的可复现性，使其他研究人员能够识别实际运行的内容。
• 在列出数字之前，先说明实验为何重要。
• 选择恰当的参照点进行比较：基线、前一次运行、消融对照、预期行为或已发表数据。
• 保留不确定性。若缺少依据，应明确标出并询问最少量的必要信息。
• 面向目标读者撰写。实验记录可以内容密集；导师进展更新则应突出决策、依据和后续步骤。

步骤 1 - 确定报告类型

确定报告模式：

• single-experiment：一次运行或一项受控比较
• ablation-report：测试单一因素的多个变体
• batch-summary：来自参数扫描或实验批次的多项相关运行
• mentor-update：简明的进展报告，侧重决策讨论
• paper-section：经过润色、旨在纳入论文的文本

同时确定：

• 受众
• 输出格式：Markdown、LaTeX、幻灯片大纲或聊天草稿
• 保存路径（如果用户需要文件）
• 预期篇幅
• 是否提供图表、表格、配置、日志或笔记本

如果用户没有指定格式，默认使用 Markdown。如果用户要求生成文件但未提供路径，则使用：

docs/reports/experiment_report_YYYY-MM-DD.md

步骤 2 - 收集依据

优先使用一手依据，而非记忆。

查找：

• 实验命令或脚本
• 配置文件和参数覆盖项
• 随机种子和运行次数
• 数据集名称、划分、预处理方式和样本数量
• 模型、方法变体、检查点或算法版本
• 相关的硬件和运行时间
• 指标、日志、结果表、图表和失败案例
• 可用时的 Git 提交哈希或代码版本

可用的本地检查包括：

git rev-parse --short HEAD
find . -maxdepth 3 -type f \( -name "*.yaml" -o -name "*.yml" -o -name "*.json" -o -name "*.csv" -o -name "*.md" \)
find . -maxdepth 4 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.pdf" -o -name "*.svg" \)

如果用户只提供了非正式笔记，使用这些内容，但要明确标出缺失的可复现性细节。

步骤 3 - 梳理实验脉络

起草前，将实验内容整理为：

• 问题：本实验试图了解什么？
• 动机：这个问题为何重要？
• 假设：我们预期什么结果，原因是什么？
• 方法：与基线相比，改变了什么？
• 控制项：哪些内容保持不变？
• 测量：哪些指标能够回答这个问题？
• 结果：发生了什么？
• 解读：结果说明了什么？
• 决策：下一步应该做什么？

对于消融实验或参数扫描，应明确自变量，并确保比较公平。

必需的报告结构

除非用户要求使用其他格式，否则使用以下章节：

# [Experiment Report Title]

## Summary
## 1. Experiment Motivation
## 2. Experiment Setup
## 3. Core Algorithm or Method
## 4. Metrics
## 5. Results
## 6. How to Read the Figures
## 7. Interpretation
## 8. Conclusion and Discussion
## 9. Limitations and Caveats
## 10. Next Steps
## Reproducibility Notes

如果不存在核心算法，则写明“Not applicable”，并简要解释本实验改动的是数据、超参数、评估、基础设施还是分析。

如果没有图表，则省略“如何阅读图表”一节；如果表格是主要依据，也可以将其替换为“如何阅读表格”。

各章节指南

摘要

用 3-6 条要点概述：

• 实验问题
• 最重要的设置细节
• 核心结果
• 解读
• 建议的下一步

1. 实验动机

说明实验背后的研究或工程原因：

• 要测试的问题
• 预期机制
• 结果为何会影响项目
• 实验支持哪项决策

2. 实验设置

提供足够详细的信息，以便复现或审查运行过程：

• 数据集、划分、预处理
• 基线和对比变体
• 关键超参数和参数变更
• 训练／评估命令、配置文件或运行 ID
• 随机种子和试验次数
• 相关时注明硬件、运行时间和代码版本

重要设置超过五项时，请使用表格列出参数。

3. 核心算法或方法

仅在理解实验所需的层面描述算法：

• 输入内容
• 输出内容
• 关键步骤或目标
• 相较于基线的新内容或差异
• 会影响结果解读的复杂度、假设或实现细节

除非受众需要，否则不要过度解释标准背景知识。

4. 指标

针对每项指标，说明：

• 定义
• 方向：越高越好、越低越好或目标范围
• 单位
• 汇总方式：均值、中位数、最佳检查点、最终轮次、置信区间或标准差
• 与实验问题的相关性

标明可能相互冲突的指标。

5. 结果

先呈现结果，再进行解读。

使用：

• 表格呈现精确的数值对比
• 图表呈现趋势、分布或定性示例
• 简短文字说明主要差异

务必明确指出基线，并尽可能报告绝对值和有意义的差异。

6. 如何阅读图表

针对每张图，说明：

• 图表要展示的内容
• x 轴：变量、单位和刻度
• y 轴：指标、单位和方向
• 图例：方法名称、分组、颜色、标记或线型
• 是否存在误差线或阴影区域
• 数据点代表单次运行、平均值、检查点、轮次还是样本
• 读者应注意的主要视觉模式

如果坐标轴使用对数刻度、经过归一化、裁剪或无单位，请明确说明。

7. 解读

结合观察到的结果，回到实验动机：

• 假设是否得到支持
• 相较于基线有哪些变化
• 可能的解释
• 其他可能的解释
• 意外结果或负面结果
• 证据是否足以采取行动

如果只有一个随机种子、统计证据薄弱或缺少对照，请使用审慎措辞。

8. 结论与讨论

说明实际结论：

• 我们学到了什么
• 结果支持哪项决策
• 应保留、舍弃还是进一步测试该方法
• 结果对更广泛的项目有何影响

9. 局限性与注意事项

列出可能改变结论的风险：

• 随机种子数量较少
• 数据集或子集范围狭窄
• 缺少基线
• 训练不稳定
• 可能存在实现错误
• 指标不匹配
• 数据泄漏或评估污染风险
• 硬件／运行时间限制

10. 后续步骤

提出具体的后续工作建议：

• 一项立即进行的验证步骤
• 一项高价值的扩展
• 一项必要时进行的清理或文档工作

将每项后续步骤与其要消除的不确定性联系起来。

项目记忆回写

如果项目使用 research-project-memory，请在报告草拟完成后写回结果：

• memory/evidence-board.md：已完成的 EVD-### 摘要、来源路径、关联的主张 ID、局限性和确定性
• memory/provenance-board.md：从运行指针、CSV、报告、聚合规则到论文候选内容的来源与证据可追溯性
• memory/claim-board.md：推动关联主张走完生命周期，例如 supported、weakened、revised、evidence-needed、provisional 或 cut
• memory/risk-board.md：关闭已缓解的风险，或添加结果暴露的新风险
• memory/action-board.md：报告中的后续步骤，包括重新运行、撰写、修订方法、暂缓或终止的决定
• memory/handoff-board.md：当结果可交由 paper-result-asset-builder、paper-evidence-board、result-diagnosis 处理或用于写作时，创建交接记录
• memory/phase-dashboard.md：如果项目进入证据制作、论文素材构建、起草阶段，或因结果削弱某项主张而退回，请更新当前阶段关卡
• 工作树 .agent/worktree-status.md 中的“Local Hot Results”：在代码工作树中工作时，始终先在此处记录结果；这是进行中和中间结果的默认写入位置
• <ProjectRoot>/memory/hot-results.md：仅当结果已确认、位列项目最重要的 5–7 项结果之中，且直接改变项目级主张时，才将结果归档至此；进行中或仅限工作树的工作不得写入此处
• memory/current-status.md：最新可靠的实验状态和下一次会话的起始点

不得将解释写成测量事实。日志或表格中的指标使用 observed，解释使用 inferred。

输出质量检查清单

定稿前，请检查以下各项：

• 报告说明了实验问题和决策背景
• 列出了所有关键参数和基线
• 指标包含方向和单位
• 结果与解释分开呈现
• 每张图表都有阅读指南
• 对缺失的证据进行了标注，而非凭空捏造
• 结论未超出数据所能支持的范围
• 后续步骤切实可行
• 存在相关项目记忆时，已更新项目记忆