需要把调查/对话结论沉淀成可分享 HTML 文档时：用…

当用户调用 /readout、说「write this up」「turn this into a doc/page」「make a readout」，或要求可读、可分享的文档来记录发现/解释某事时，用 snapshot 或 research 模式产出 ~/.readouts 下的自包含 HTML readout。

适用场景

解决思路

1. 先判定模式：snapshot mode（对话中调用，如「write this up」，以当前对话累积的发现为素材）或 research mode（全新调用，如「/readout on how github webhook events are processed」，没有对话可挖，调查本身也是任务的一部分）。
2. 把调用 readout 当作 side task：主 agent 只负责明确范围、给子 agent 一个好 brief、然后让路；挖掘/研究和写作交给子 agent，避免大任务进入主上下文窗口。
3. 启动前先锐化范围：要能列出文档将回答的具体问题；列不出来就先访谈用户。
4. 访谈时问 2–4 个有针对性的问题，给具体选项而不是开放题；先快速看代码或主题，让选项真实（如子系统、入口点、竞争性关注点）。例如对「/readout on how github webhook events are processed」可问：关心 inbound triggers、post-back 还是两者？要 current-state reference 还是 gotcha hunt？涉及哪些 repo？
5. 始终确定深度和受众：高层概览 vs 带行级依据的深入机制；个人笔记 vs 分享给团队。
6. 尊重用户的「不知道/随便」：「Just a high-level overview」是有效回答，记入 brief 后继续，不要继续盘问；即便如此也尽量抽出读者最需要回答的 2–3 个问题，具体性决定 readout 是否有用。
7. 范围已经具体时跳过访谈：聚焦对话的 snapshot，或精确的 research 请求，都不需要提问。snapshot 模式通常由对话本身提供问题；只有当调用没有表明要包含哪些线程时才问。
8. 写一个约 10–20 行的简短 brief，携带 pointer 而非 payload。
9. Brief 包含：工作标题/主题和模式（snapshot 或 research）；文档必须回答的具体问题（来自对话或访谈）；深度和受众；范围：要覆盖的线程/子系统，以及明确排除的内容。
10. Snapshot 模式 brief：列出值得作为文档中心的 headline conclusions，每条一行；子 agent 会自己从对话历史中拉取完整内容，不要整段粘贴发现。
11. Research 模式 brief：给出起始 pointer，例如已知的入口文件、符号或目录。
12. Brief 包含用于支撑工作的 repos/directories 的绝对路径。
13. Brief 包含每个 repo 的 hosted URL 和已知的 examined commit（如 `github.com/org/repo @ abc123`），以便文档超链接代码引用。
14. 通过 `run_agents` 只启动一个 local 子 agent。必须 local：文档落在用户文件系统并用其浏览器打开。子 agent 命名为 `readout-<topic-slug>`。
15. 用模板构造子 agent prompt。必须包含：brief；与模式匹配的 source-material block；snapshot 模式还要包含你的 agent run ID（来自 orchestration runtime context 的 `current_run_id`），以便子 agent 用 `search_conversation_history` 挖掘父对话；要求子 agent 写之前读本 skill 目录的 `references/doc-guide.md`；输出路径约定和完成协议。
16. 子 agent prompt 的 snapshot source material：父对话 agent run ID `<current_run_id>`；用 `search_conversation_history` 且 `agent_run_id` 设为该 ID；做多次针对性查询——brief 中每个问题一次——而不是一次宽泛查询；针对性查询能挖出更多可用细节。代码库在 `<absolute paths>`；对话是起点不是牢笼：断言前先验证文件引用，某节需要更多深度以独立成立时，去读代码补全。
17. 子 agent prompt 的 research source material：直接在 `<absolute paths>` 的代码库中调查；让 brief 的问题驱动调查：追踪实际代码路径，读真实实现，每个断言都用 file:line 引用落地；区分已验证与推断；不要用通用知识填充文档——价值在于这是对该代码库为真的内容。
18. Research 模式在已知时提供 repo host + commit 以生成链接代码引用：`<github.com/org/repo @ commit>`（否则从 git 推导；见 doc guide 的「Linked code references」）。
19. 从规范模板 `<skill-directory>/assets/template.html` 开始；它的 `data-readout` chrome blocks 必须逐字复制，使每个 readout 看起来一致。写作前读 `<skill-directory>/references/doc-guide.md` 并遵循。
20. 输出：把 ONE self-contained HTML 文件写到 `~/.readouts/<YYYY-MM-DD>-<topic-slug>.html`；如果 `~/.readouts` 不存在则创建；如果名字被占用则加后缀 `-2`、`-3`……；用 `date +%F` 获取日期。
21. 当 repo 已 checkout 时，按 doc guide 嵌入被引用的源码：`<skill-directory>/scripts/embed_snippets.py`。
22. 刷新 readouts 索引：`python3 <skill-directory>/scripts/update_index.py`（完全重新生成 `~/.readouts/index.html`，列出每个 readout）。
23. 文件写好后，用 `open <path>` 打开；如果环境是 headless 则跳过。
24. 向 orchestrator 汇报：绝对文件路径、2–3 句话的文档内容总结、以及任何无法验证的内容。
25. 主 agent 启动子 agent 后：恢复手头工作或结束回合；子 agent 的完成消息会自己到达；到达时把文件路径和一句话描述转告用户。research 模式的新对话可能没有别的事，直接结束回合。除非用户要求等待文档，不要坐在 wait loop 里。
26. Fallback：子 agent 不可用或被拒绝时，自己按 `references/doc-guide.md` 产出文档；如果有 research subagent，可把对话挖掘或代码调查委托给它，以保持上下文精简。
27. Fallback：snapshot 模式下子 agent 不能搜索对话历史（它会汇报此问题）时，回复子 agent 一份蒸馏后的 findings dump 让它继续；这是唯一适合把 payload 放进 prompt 的情况。
28. Fallback：用户提供材料而非对话（transcripts、files、links）时，把这些材料当作 source；工作流其余不变。

适用边界 · 注意事项

• 只需要即时聊天回答、不需要持久化或可分享文档时，不要生成 readout。
• 范围已足够具体但用户希望在主对话中直接交互式讨论、不希望启动后台子 agent 时，不适合按完整 orchestrator 流程执行。
• 环境不能写入 `~/.readouts` 或无法交付 HTML 文件，且不接受本地 fallback 时，不适用。