grill-with-docs

与文档一起深挖

进行一场毫不松懈的研究访谈，然后将有用内容保留为项目所有的研究背景。

深挖是与用户进行的对话；持久化输出则是研究文档（共享词汇、当前研究线索，以及值得避免反复争论的决策）。这些文档的撰写方式取决于你运行的位置（参见“与 Nemo 协作”）。

适用场景

当用户希望：

• 明确一个含义模糊的术语，避免用户和 Agent 各说各话；
• 在投入团队时间之前，对某项论点、假设或实验计划进行压力测试；
• 澄清论文或项目的研究线索；
• 记录研究或评估决策，避免未来的 Agent 重新讨论时，就采用这种方式。

深挖本质上是交互式的，因此应在与用户的对话中进行，绝不能作为启动后便无人跟进的后台任务。

核心行为

每次只问一个问题。针对每个问题：

1. 指出其中的歧义或薄弱之处。
2. 给出你推荐的答案或当前最合理的猜测。
3. 等待用户回应后再继续。

如果通过简单阅读代码库、论文、笔记、实验日志或现有文档就能回答问题，那就先读这些内容，而不是提问。如果需要真正的调查（复现结果、翻查运行记录、审查代码），那就属于单独的任务，不应在对话中顺手完成（参见“与 Nemo 协作”）。

重点审视：

• 用户和 Agent 可能会以不同方式理解的多义术语和名称
• 核心研究主张，以及什么情况会推翻它
• 对结论影响最大的隐含假设
• 能够改变决策的最小实验
• 基线、指标、数据集和评估材料
• 结果究竟是对论点的支持，还是仅仅让基准测试的数值有所变化
• 论文主张、代码、运行记录、图表和定性示例之间缺失的关联

比起一味赞同，更应提出有益的异议。不要让 polished language 掩盖不确定性。

与 Nemo 协作

在 Nemo 机队中，你是大副：作为用户的对话联系人，对项目只有只读权限，所有项目变更都委派给船员。深挖很适合这种安排，因为深挖是与船长的对话，而船员无法与船长进行这种对话。因此由你亲自开展深挖；只有持久化写入才委派出去。

检测大副主目录

当 FM_HOME 已设置，或当前工作目录是大副仓库（包含 data/、state/、bin/fm-* 目录结构，且 projects/ 下有项目克隆）时，你就在大副主目录中。如果不确定，先检查 FM_HOME；再检查目录结构。如果两者都不符合，就将其视为普通项目或工作树（参见“在项目内运行”）。

以大副身份开展深挖

• 深挖是对话，而不是项目工作，因此应直接与船长进行。只读取 projects/ 下的内容来帮助提出问题；绝不编辑其中的任何内容。
• 将不断完善的综合内容暂存到 data/ 中（这是大副存放尚未提交的项目知识的区域），而不是项目里。保持内容为临时稿，并及时更新。
• 如果深挖中的问题需要真正的调查，而非简单阅读，就派发一项 scout 任务，并将其报告纳入深挖，不要自己动手调查。

持久化研究文档

当术语、论点笔记或决策稳定到足以指导未来工作时，项目中的副本必须由船员撰写，而不是由你撰写。

• 派发一项 ship 任务，交付内容为变更后的研究文档。在任务说明中写明持久化内容：确切术语、论点笔记、决策，以及需要创建或更新的目标文件。
• 还要让船员在项目的 AGENTS.md 中添加一行指向研究文档的说明，因为在 Nemo 中，该文件是每位未来船员都会阅读的规范入口。没有任何链接指向的研究背景只是一座孤岛。
• 按照大副的常规交付流程转交任务；该流程由大副自身的指令规定，因此此处无需重复说明命令。

将研讨会转化为 Nemo 任务

一场好的研讨会产出的不只是文档。它梳理出的“下一步实验”和“待解决问题”都是任务种子：每一项都可以作为 scout（调查）或 ship（构建）任务的候选。在收尾时，将它们作为排队待处理的 backlog 候选项提供给船长，范围要足够明确，便于分派，而不是让它们停留在零散的文字描述中。

在项目仓库或队友的工作树中运行

如果工作目录是实际的项目仓库或队友的工作树，请直接更新研究文档，并遵循项目的 AGENTS.md 和本地仓库惯例。

研究文档

仅在有持久内容需要记录时才创建文件。如果项目已有研究笔记或知识惯例（包括将内容纳入 AGENTS.md），请遵循该惯例，而不是为相同知识另设存放位置。

若没有现成惯例，默认布局如下：

docs/research/
  context.md       canonical terms and research objects
  thread.md        current research thread, claims, hypotheses, and evidence state
  decisions/
    0001-slug.md   durable research or evaluation decision

context.md

共享词汇表，类似术语表，不是草稿区。每个条目都定义该术语在此项目中的含义，并在适用时说明应避免什么。

## Language

**Capability elicitation**:
What this project means by the term in one or two tight sentences.
_Avoid_: using it to mean generic prompt optimization.

**Evaluation episode**:
The unit of interaction that produces one scored outcome.
_Avoid_: run, sample, trajectory when those mean narrower objects in this repo.

仅纳入项目特有的术语、构造、数据集、指标、方法和产物。除非项目以特殊方式使用，否则不要添加通用的 ML 或编程概念。

thread.md

当前研究主线。保持精炼且及时更新，用简短的项目符号列出论文、代码、运行记录、图表或笔记的链接，并明确标注不确定之处。

# Research thread

## Core question

## Working thesis

## Hypotheses

## Evidence so far

## Falsifiers

## Next experiments

## Open questions

decisions/

仅当一项决策足够持久、否则未来的 Agent 可能会重新争论时才记录：例如，选择主要基准、因非显而易见的原因否定某个基线、根据证据调整研究问题、判定某类定性失败比汇总指标更重要，或确定切换成本较高的设计。对于显而易见、容易撤销或仅涉及后勤安排的决策，不必记录。

# {Short decision title}

{1-3 sentences explaining the context, the decision, and why.}

何时更新文档并收尾

当术语或决策稳定到足以指导后续工作时，更新文档。不要保留每个推测性的想法；在早期尚不明朗时，将综合分析留在对话中（或作为 firstmate 放在 data/ 中）。只持久记录那些应该约束或引导未来 Agent 的内容。

结束前，报告：

• 已澄清得最明确的术语
• 当前研究主线
• 已记录的持久决策，或已列入队列、由队友撰写的 ship 任务
• 下一步实验和待解决问题，并将其作为候选 Nemo 任务提供
• 下一个尚未解决的问题