update-experiment-docs

name: update-experiment-docs description: Update research and experiment documentation for algorithm work. Covers four stages: pre-research planning (1-pager with SCQA), post-research findings synthesis, pre-experiment setup (environment config recording), and post-experiment results documentation. Detects perfectionism signals and enforces MVP documentation. Use when starting research, after reading papers, before running experiments, or after experiments complete. disable-model-invocation: true

Skill: Update Experiment & Research Docs

这个 skill 是什么

面向算法/实验驱动工作的文档更新 skill。覆盖从调研到实验的全链路：

阶段	做什么	输出
调研前	用 1-pager + SCQA 规划调研方向	`research-1pager.md`
调研后	整理调研发现、对比、结论	调研报告
实验前	记录实验环境、配置、假设	实验配置记录
实验后	分析结果、记录发现、更新假设	实验结果报告

核心理念来自 start-with-1pager：方向上认真，执行上糙一点。文档的 v0 就是粗糙的，目的是有起点，不是完美方案。

何时启用

不要用自动判断强制选 workflow。先问用户当前处于什么阶段，然后提供选项：

阶段	用户说法	可选 workflow
要开始新调研	"我想调研一下 X"	A: 1-Pager 规划
调研完了想整理	"我刚读完几篇论文"	B: 调研发现整理
准备跑实验	"我要开始跑实验了"	C: 实验配置记录
实验跑完了	"实验跑完了，帮我整理一下"	D: 实验结果记录

灵活使用：用户不一定按 A→B→C→D 顺序走。可能直接从 B 开始（已有想法不想写 1-pager），可能跳过 C 直接跑 D。尊重用户的实际节奏，提供对应模板即可。

如果用户只说"帮我更新文档"但没说清楚，问一次。真的判断不出来再问，不要预设默认 workflow。

文档位置约定

用户可能指定任何路径。如果用户没有指定，默认输出到项目下最合理的位置——通常是已有的 docs/research/ 或 docs/experiments/，但如果项目有其他文档目录约定，遵循项目的实际结构。

文件命名参考：

调研类：<topic-slug>.md 或 <topic-slug>-1pager.md
实验类：<experiment-slug>.md 或 <experiment-slug>-setup.md

不要强迫用户接受固定路径。如果用户说"写到这里"或自己给了路径，直接用。

Workflow A: 调研前规划（1-Pager）

Step A0: 方向 vs 执行检查

先问用户："你现在'想'的是方向还是执行？"

想"要调研什么 / 为什么调研 / 怎么衡量调研成功" → 方向 → 进 Step A1
想"用什么框架 / 跑哪个模型 / 用什么数据集" → 执行 → 这是完美主义信号
- 提醒：执行细节动手做就知道了，现在该想方向
- 如果用户坚持要先定技术细节，提醒"先有个粗糙方案，动手中可以调整"

Step A1: 填写调研 1-Pager

给用户提供模板（agent 不要替用户填实质内容，只引导该填什么）：

# [调研主题] 1-Pager

## 1. Background (S)
- 这个方向在解决什么问题？
- 谁（什么场景）在乎这个问题？

## 2. Problem (C)
- 现状哪里不够好？
- 为什么现在做这个调研？

## 3. Hypothesis (一句话)
我猜测的核心判断：___________

## 4. 调研范围（MECE，2-4 个维度）
- 维度 1: ...
- 维度 2: ...
- 维度 3: ...
（相互独立、完全穷尽）

## 5. Success criteria
调研到什么程度算"够了"？
- [ ] 读完 X 篇核心论文
- [ ] 对比 Y 个方案的优缺点
- [ ] 输出 Z 结论

## 6. Risks
我最可能错的假设是什么？

Step A2: 粗糙度检查（5 条判据）

1-pager 写完后跑检查。任何 ❌ 都是完美主义入侵：

⏱️ 用时 < 1 小时？
📝 Hypothesis 只有 1 句话（不是几段）？
🧩 调研范围是 MECE 的（不重不漏）？
🤔 用户接受这个调研结论可能推翻当前假设？
📏 总长 ≤ 1-2 页？

≥ 1 个 ❌ → 提醒 "v0 就是粗糙的，目的是有起点，不是完美方案"。

Step A3: 输出文件

将 1-pager 写入用户指定或默认的位置。如果用户没有指定路径，写入 docs/research/<topic-slug>-1pager.md（项目没有这个目录则创建）。

Workflow B: 调研后整理

Step B1: 确认调研输入

问用户（或自动扫描）：

读了哪些论文/资料？（提供列表或链接）
做了哪些笔记？
有没有跑过 demo 或 baseline？

Step B2: 结构化调研发现

按以下结构整理（结论先行，用 SCQA 开场）：

# [调研主题] 调研报告

> **TL;DR**（一句话结论）：_____________

## 1. Overview (S-C-Q-A)
- **Situation**: 这个领域的现状是...
- **Complication**: 但存在一个问题...
- **Question**: 所以关键问题是...
- **Answer**: 我们的判断是...

## 2. 方案对比（MECE 分组）

### 方案 A: [名称]
| 维度 | 描述 |
|---|---|
| 核心思想 | |
| 优势 | |
| 劣势 | |
| 适用场景 | |
| 关键论文/资源 | |

### 方案 B: [名称]
（同上结构）

## 3. 对比总结

| 维度 | 方案 A | 方案 B | 方案 C |
|---|---|---|---|
| 效果 | | | |
| 复杂度 | | | |
| 资源需求 | | | |
| 可落地性 | | | |

## 4. 结论与建议
- 推荐方案：____，因为____
- 不推荐方案：____，因为____
- 下一步：____

## 5. 参考资源
- [论文/链接 1](url)
- [论文/链接 2](url)

Step B3: 关联到 1-pager

如果之前有 1-pager（Workflow A 的输出），检查：

Hypothesis 是否被验证/推翻？
调研范围是否都覆盖了？
Success criteria 是否达成？

在调研报告末尾加一个"vs 1-pager"小节，对比差异。

Step B4: 输出文件

将调研报告写入用户指定或默认的位置。默认 docs/research/<topic-slug>.md。

Workflow C: 实验前记录

Step C1: 确认实验目标

问用户：

这个实验要验证什么假设？
和之前的调研/实验有什么关系？

Step C2: 记录实验配置

用以下模板整理：

# [实验名称] - 实验配置

## 1. 实验目的
- 要验证的假设：___________
- 这个实验属于哪个调研方向：[链接]

## 2. 实验环境

### 硬件
| 项目 | 配置 |
|---|---|
| CPU | |
| GPU | |
| 内存 | |

### 软件
| 项目 | 版本 |
|---|---|
| OS | |
| Python | |
| 关键依赖 | |

### 数据集
| 项目 | 描述 |
|---|---|
| 名称 | |
| 规模 | |
| 来源 | |

## 3. 实验设计

### 变量
| 类型 | 变量 | 值/范围 |
|---|---|---|
| 自变量 | | |
| 因变量 | | |
| 控制变量 | | |

### 实验组
| 组名 | 配置差异 | 预期效果 |
|---|---|---|
| baseline | | |
| exp-1 | | |
| exp-2 | | |

## 4. 执行命令

```bash
# 记录复现实验所需的完整命令

5. 成功指标

达到什么指标算实验成功？
什么结果说明假设错误？

6. Risks

最可能出问题的环节？
如果失败了，排查顺序？


### Step C3: 输出文件

写入用户指定或默认的位置。默认 `docs/experiments/<experiment-slug>-setup.md`。

---

## Workflow D: 实验后记录

### Step D1: 收集实验结果

问用户或自动收集：
- 实验跑了吗？有没有报错？
- 产出数据/图表在哪里？
- 有没有关键发现（出乎意料的）？

### Step D2: 整理实验报告

```markdown
# [实验名称] - 实验结果

## 1. 实验概览
| 项目 | 内容 |
|---|---|
| 实验名称 | |
| 日期 | |
| 状态 | 成功 / 部分成功 / 失败 |
| 对应假设 | |

## 2. 结果摘要
- 一句话结论：___________

## 3. 数据与指标

| 实验组 | 指标 1 | 指标 2 | 指标 3 | 备注 |
|---|---|---|---|---|
| baseline | | | | |
| exp-1 | | | | |
| exp-2 | | | | |

## 4. 结果分析

### 4.1 与预期对比
- 符合预期的部分：____
- 出乎意料的部分：____

### 4.2 根因分析
（针对出乎意料的结果）

### 4.3 可视化
（如果有图表，插入或引用）

## 5. 结论
- 假设验证结果：✅ 支持 / ❌ 不支持 / ⚠️ 不确定
- 关键发现：____
- 这个结果意味着：____

## 6. 下一步
- 基于这个结果，接下来做什么？
- 需要调整假设吗？
- 需要补充实验吗？

## 7. 问题与待办
- [ ] 待解决的问题
- [ ] 待验证的想法

Step D3: 回链上游文档

如果有关联的调研（Workflow B），更新调研报告的结论部分
如果有关联的 1-pager（Workflow A），更新 hypothesis 状态
在实验报告末尾添加引用链

Step D4: 输出文件

写入 docs/experiments/<experiment-slug>.md。

完美主义信号词典

实验/调研文档写作中，用户说这些话时识别并引导：

信号词	真实含义	建议回应
"我再跑几个实验一起写"	用数据量拖延写作	"先写已经有的，新的补上就行"
"等我整理完所有数据"	完美主义	"粗糙表格也行，先有再说"
"这个结论还不够严谨"	学术洁癖	"1-pager 的结论就是粗糙假设，实验会验证"
"我要先画个好看的图"	执行细节优先	"先用文字描述结论，图可以后补"
"这个调研还不够全面"	调研范围失控	"回到 1-pager 的 MECE 范围，够了就行"

输出格式要求（飞书/Notion 兼容）

所有文档输出遵循以下格式规范，确保可以直接粘贴到飞书/Notion 中展示：

标题层级：使用 # / ## / ### 三级以内，不嵌套更深
表格优先：对比类内容用 Markdown 表格（飞书自动渲染）
代码块：命令/配置用代码块，标注语言
列表层级：不超过 2 级嵌套
引用：用 > 引用关键结论
链接：用相对路径链接相关文档（飞书会自动转换）
Emoji：仅在状态标记处使用（✅ ❌ ⚠️），不用于装饰

给 Agent 的执行提醒

不要替用户填写实质内容。1-pager 里的答案、实验假设、结论判断必须是用户的——agent 只提供模板、提醒格式、检查 MECE。
保持限时压力。调研 1-pager < 1 小时，实验配置记录 < 30 分钟。
关联文档。新文档创建后，检查是否有相关的旧文档需要更新。
增量更新。不要推翻重写——在现有文档上追加/修改。
允许粗糙。v0 就是粗糙的，这是功能，不是 bug。
跨实验追溯。如果用户有多个相关实验，帮他们建立引用链（实验 → 调研 → 1-pager）。
不要强迫走固定流程。用户不一定按 A→B→C→D 走，尊重用户的实际节奏。提供对应模板就行，不要催促用户"应该先写 1-pager"。
路径灵活。用户给了路径就写用户给的位置，不要强迫 agent 去找固定目录。