iterate-from-user

从用户处迭代

来源：用户直接提供，或通过用户指向的内容（文章、议题、规范、代码仓库）。输出：一个经用户确认的 Proposal 区块，并交回 iterate-ml-experiment。

输出约定（先阅读，再看正文）

此技能绝不会写入 journal/ 文件，也绝不会撰写验收标准。它会以对话文本的形式返回单个 Proposal 区块（完整格式见底部的 § 返回内容）： Question、Motivation（包含 Source 字段——引文、URL 或路径）、Method outline、Open gaps。每种分支都必须满足以下要求：

• 三个塑造问题均已回答（见 § 三个塑造问题）。
• 综合确认关卡已触发，且用户已表示同意（见 § 返回前确认）。
• Source 字段具体明确：用户的引文、包含具体主张的文章 URL、gh issue 链接，或带行号的规范文件路径。

不存在“无提案”这一结果：此技能仅在用户从父级的来源菜单中选择 user 时触发。如果用户手头没有任何内容，父级菜单会再次显示。

停止条件

• 不要写入 journal/ 文件。 这属于 iterate-ml-experiment。此技能会将提案作为 对话文本返回；父技能负责起草文件。
• 不要凭记忆推断源内容。 如果用户提到一篇文章、一个问题或一个文件，请获取 / 阅读它。 不要根据标题或一句话描述重构内容。
• 返回前先确认。 只有在用户明确表示“是的，这就是我想要的”之后，才能将提案返回给 父技能。必须先提出综合问题，再输出任何 Proposal (...) 块。随口说“嗯”“也许”或“有意思”都不算确认。请参阅 § 返回前确认。
• 从 GitHub 获取任何内容之前，先检查 gh 身份验证状态。 在调用任何 gh issue view / gh api 之前，运行 gh auth status （开销很小，且结果会缓存）。如果未通过身份验证，请让用户自行运行 gh auth login（在提示中建议使用 ! gh auth login），或直接粘贴问题正文。gh 调用失败会产生令人困惑的错误；身份验证检查能明确失败原因。
• 返回前标出目标变化。 如果用户的想法（或源内容）实质性改变了 JOURNAL.md Status 中记录的项目目标——输出形式不同（点估计 → 预测区间）、下游使用方不同（离线批处理 → 在线服务）、指标类别不同（平方误差 → 覆盖率）——请在返回提案前将其作为问题提出：“这会将 JOURNAL.md Status 从 更新为 ；请先确认或修改目标？” 父级的逐实验设计说明不应在 Status 块仍反映旧目标时，悄然重新定义成功标准。
• 新增依赖必须经过确认，不能想当然。 如果提案需要项目现有环境之外的库（例如，文章使用了 lightgbm / pytorch / jax），不要将其作为既定事实悄然写入 Method outline。请将其标记为待解决事项（“此方法需要 ；是否可以添加，还是应该调整以适配现有技术栈？”），并将决定留给 data-science-python-stack + 用户。在用户答复之前，库名称只能出现在 Open gaps 下，不能出现在 Method outline 中。
• 领域特定断言需要用户确认。 如果源内容提出了仅凭文章 / 问题 / 规范无法针对我们的数据集证实的说法——例如，“特征 X 与目标单调相关”“交互 Y 对此资产类别很重要”“由于用例是单边的，因此指标 Z 正确”——请将每项断言列入 Open gaps，并在返回前询问用户。不要将带有论文色彩的猜测当作事实提交。
• Harness 层级的“不要提澄清问题”指令不适用于此技能的确认关卡。 入口处的 AskUserQuestion（文章链接 / 资源链接 / 自由文本）以及 §“返回前确认”综合确认环节，都是操作约定关卡，而非澄清问题。无论 harness 层级有何提示，它们都必须执行。尤其是综合确认环节不可跳过，即使用户的意图看起来“显而易见”也不例外——设置此关卡，就是为了避免 Agent 的复述遗漏细微的表达角度。请参阅项目 CLAUDE.md §“技能咨询约定”规则 3。

入口 AskUserQuestion

调用此技能时，首先使用 AskUserQuestion——提供三个互斥选项，不设默认选项：

• article-link — 用户有一篇想改编到此项目中的科学文章（论文、博客文章或库文档）。Agent 阅读、综合整理并确认。
• resource-link — 用户有 GitHub issue、规范文件、笔记仓库或其他描述了尝试内容的具体资料。Agent 阅读资料，以三个问题的视角进行总结并确认。
• free-text — 用户有一个口头或书面的想法，会直接进行描述。Agent 通过三个塑形问题复述该想法并确认。

使用规范的 AskUserQuestion 界面；只有在当前会话中确实无法使用时，才退而使用纯文本列举选项。

例外 — 已预先确定的入口。 当 iterate-ml-experiment 在来源菜单层级已通过自由文本处理确定分支后调度至此处时（用户已将 URL、issue 链接或具体想法直接输入来源菜单的 AskUserQuestion），父级会传入已确定的分支和内容。跳过此 AskUserQuestion，直接进入匹配的分支，并使用已提供的内容——用户实际上已经回答了此问题。分支末尾的综合确认关卡仍然生效；只有入口问题会被跳过。

三个塑形问题

此技能返回的每个 Proposal——无论属于哪个分支——都必须回答：

1. 我们想要了解什么？（将“尝试 X”转化为假设）
2. 为什么是现在？（此想法出现的具体原因——引用用户的话、链接文章、引用 issue / 文件）
3. 与上一个实验相比有哪些变化？（用文字说明会改动 src/<pkg>/ 中的哪个文件，而非代码）

如有缺漏 → 询问用户。不要捏造信息。没有第四个“如何判断它是否成功”的问题——验收标准不属于此技能的范围。

三个分支

分支 A — article-link

用户选择 article-link 并提供 URL（直接粘贴、后续提示，或隐含在父级消息中）。

1. 使用 WebFetch 获取内容（如果用户只提供了主题，且需要定位具体论文，则先使用 WebSearch）。阅读摘要以及与该技术最相关的章节。
2. 映射到三个塑形问题。 文章提出了什么？采用该方法需要对 src/<pkg>/ 做哪些具体改动？“为什么是现在？”要逐字引用文章。
3. 指出迁移风险。 如果文章使用了不同模态、大得多的数据集或不同的目标类型，请说明该技术可能无法顺利迁移的方面。Proposal 的 Open gaps 中要明确写出这些风险。
4. 将新依赖标记为未解决的问题，不要悄悄将其添加到 Method outline 中（见上文的停止条件）。
5. 在 Open gaps 中将领域特定的断言标记为 [needs user confirmation]。
6. 返回前先确认——参见 § 返回前确认。

如果本轮无法获取内容（没有可用工具、URL 无法访问）： 仍然列出三个塑形问题（可以使用占位内容），将领域相关的说法放入 Open gaps 并标记为 [needs user confirmation]，同时展示 § 返回前确认中的复述内容。不要因为未能获取正文就跳过这些内容。

分支 B — resource-link

用户选择 resource-link 并指定：

• GitHub issue：按以下优先级解析，然后运行 gh issue view <N> --json title,body,labels,url（如果正文 信息不充分，则通过 --json …,comments 拉取最近约 5 条评论， 或使用 gh api repos/<owner>/<repo>/issues/<N>/comments — 提案通常在讨论串中）。
• 规范文件 / 笔记文件：Read 用户指定的文件； 不要遍历相邻文件。
• 参考仓库：读取 README.md / SPEC.md / NOTES.md 或用户指定的其他顶层提案文档。不要遍历整个目录树 — 那样会掩盖关键信息。

GitHub issue 解析优先级（绝不默默猜测 仓库）：

1. 用户消息中的明确 URL （https://github.com/<owner>/<repo>/issues/<N>）— 无条件优先。
2. org/repo#N 简写（probabl-ai/skore#42）— 优先于当前上下文。
3. 没有限定信息的裸 #N 或“issue 42” — 回退到当前的 gh 上下文（通过 gh repo view --json nameWithOwner 确认）。如果没有上下文，先询问用户，再获取信息。

对于所有三种资源子类型：

1. 对应到三个梳理问题。 该资源想了解什么？它如何阐述动机？src/<pkg>/ 中具体会有什么变化？
2. 具体引用来源。 Source 字段应引用 issue URL、文件路径（适用时附行号），或仓库 + 文件 — 不能只写仓库名称。
3. 标明缺口。 如果资源未回答三个梳理问题之一，将其列在 Open gaps 下。
4. 返回前确认 — 见下文。

如果本轮无法执行获取操作（没有 gh，或没有 Read）：仍然写明 gh auth status，然后写出 gh issue view <N> …（或 Read 指定文件），列出三个梳理问题，将未回答的事项列在 Open gaps 下，并展示确认复述。不要因为尚未获取 issue 正文而跳过这些步骤。

分支 C — free-text

用户选择 free-text，并直接输入自己的想法。

1. 用通俗语言梳理三个问题。 总结时引用用户原话，以保留用户自己的表述方式。
2. 将用户的话视为 Source。 提案的 Source 字段应填写用户引述（或经用户认可的一句话释义）。
3. 返回前确认 — 即使是自由文本提案，也要经过综合确认环节。Agent 对想法的复述可能会微妙地偏离用户原意。

返回前确认

所有分支中，在将提案交给 iterate-ml-experiment 前，Agent 都要向用户发送一段简短的纯文本综合说明，并等待用户明确批准：

"根据 <来源>，我理解你想要**<一句话意图>** — 具体来说，修改 src/<pkg>/<file>.py，以**<方法概要>。未解决的问题：<要点>**。交给规划器之前，这样概括符合你的想法吗？"

在用户回答“是”之前，消息只能包含上述引文段落。不要输出 Proposal ( 标题，即使标记为 PENDING / NOT RETURNED 也不行。

用户的回答决定接下来的操作：

• “Yes / confirm / go” → 返回提案。 父级技能据此起草 journal/NN_*.md。在用户确认之前，不要输出 Proposal (...) 区块。
• “No / not quite / adjust X” → 修改并重新确认。 反复调整综合说明，直到用户满意。不要返回用户尚未认可的提案。

这个确认环节不可省略。它相当于父级设计说明审批环节在用户侧的对应流程 — 能在起草设计说明之前发现误解，此时修订成本最低。即使本轮未能获取来源正文，也要展示复述。

返回内容

一个简短的结构化区块，而非设计说明：

Proposal (from: user via <article-link | resource-link | free-text>):
  Question:        <one sentence>
  Motivation:      <quote / URL / file path + the why-now reason>
  Source:          <article URL with claim | gh issue URL | spec file:line | user quote>
  Method outline:  <prose; which file in src/<pkg>/ is touched>
  Open gaps:       <transfer risks, dep questions, domain assertions
                    needing user confirmation, anything the source
                    didn't answer>

iterate-ml-experiment 会使用此内容起草 journal/NN_short_name.md。不包含 Success 字段 — 该技能有意不编写验收标准；用户会在运行后评判结果。

配套技能

• iterate-ml-experiment — 调用方；负责设计说明。
• iterate-from-skore — 唯一的同级策略；通过从上一份 skore 报告中提取信息并写入 Backlog，为 下一次实验确定来源。
• data-science-python-stack — 当文章引入新的依赖项时（见上文「停止条件」）咨询。
• build-ml-pipeline / evaluate-ml-pipeline — 负责相关文件（pipeline.py、evaluate.py、……）的维护；「方法概要」最终会涉及这些文件。