iterate-ml-experiment

迭代 ML 实验

experiments/ 之上的循环：下一步尝试什么、为什么尝试、什么算是结果，以及如何记录过程。流水线／评估机制位于同级技能中。

下一步指引 — 流程一览

session open
   │
   ├── JOURNAL.md missing / placeholder ──► § 0 Bootstrap
   │                                          │
   │                                          ├─► G-EDA (explore-ml-data: run | skip)
   │                                          │
   │                                          └─► design note → G-DESIGN → § 3 implement
   │
   ├── "what's next?" with ≥1 done row ───► § 1 summary → § 2 (sourcing; skip three-way) → § 3 implement
   │
   ├── "run finished" ─────────────────────► § 4 record outcome
   │                                          │
   │                                          └─► dispatch audit-ml-pipeline
   │
   └── "status?" / "compare X Y" ──────────► references/maintenance_modes.md

在声明本轮完成前，务必重新输出附带证据的 Pre-flight checklist。

首个操作 — 读取状态 + 输出读取集跟踪器

仅在步骤需要时，即时打开每个同级的 SKILL.md（例如，在第 3 节的 CV 策略步骤前，打开 evaluate-ml-pipeline）。不要在会话开始时预先读取全部内容。

Sibling skills (just-in-time):
  - organize-ml-workspace, data-science-python-stack,
    python-env-manager, python-api, python-code-style,
    explore-ml-data, build-ml-pipeline, evaluate-ml-pipeline,
    test-ml-pipeline, smoke-test-ml-pipeline,
    iterate-from-skore / iterate-from-user

然后，在回答前：

1. 读取 journal/JOURNAL.md。 若文件缺失或为占位内容 → 执行引导初始化（第 0 节）。 这是项目的规范摘要（Status、Data understanding (EDA)、History、Backlog）。
2. 检查 Workspace decisions 块，查看是否已有预先记录的关卡（tabular、env_manager、package、skore_mode、cv_splitter）——已记录的决策可跳过对应的 AskUserQuestion。
3. 输出 Pre-flight checklist，并填好每个复选框。
4. 使用 Mode picker，确定要阅读哪个部分。

Mode picker — 阅读后再浏览正文

每轮只阅读一个模式章节。匹配用户的意图，然后跳转。

意图／工作区状态	模式	章节
JOURNAL.md 缺失／为占位内容／History 有 0 行	引导初始化	§ 0
journal/ 尚未搭建（没有 src/、没有 experiments/）	引导初始化 → 先交接	→ organize-ml-workspace，然后 § 0
“接下来做什么？”／“继续迭代”／“提出下一步建议”——且至少有 1 条已完成记录	迭代（提出建议）	§ 1 摘要 → § 2（+ Dispatch）；跳过 § 1 的三选一
“运行结束了”／“记录结果”／“我们得到 X = …”	迭代（记录结果）	§ 4
“目前进展如何？”／“状态？”／“我们试过什么？”	项目概览	references/maintenance_modes.md § “Project overview”
“比较 X 和 Y”／“X 与 Y”	比较（只读）	references/maintenance_modes.md § “Compare past experiments”
“调整目标方向”／“其实我们关注的是 ”	目标调整	references/maintenance_modes.md § “Goal pivots”
“放弃 X”／“舍弃 X”	已放弃实验	references/maintenance_modes.md § “Abandoned experiments”
在不同条件下重做之前的实验	重新运行	references/maintenance_modes.md § Re-runs

如果看起来有两个模式都符合（“比较 X 和 Y，然后提出建议”），先选择读取模式，然后停止。重新进入 § 1 属于单独一轮。

停止条件 — 请先阅读

• 没有设计说明，就没有脚本。 在 journal/NN_*.md 存在且已填写，并且用户明确批准之前，绝不创建或编辑 experiments/NN_*.py。

• 派发是交接，不是提议。 当来源分支转交给同级技能时，由该同级技能自行获取信息。 不要要求用户粘贴问题正文、文章内容或“简短摘要”，以便跳过交接——这等于让用户代做同级技能的工作，也会丢弃该分支的引导问题和确认关卡。如果本轮无法执行派发，请说明哪个交接环节受阻，然后停止；不要用向用户提问来替代派发。

  GitHub issue URL this turn: name iterate-from-user (resource-link,
  pre-resolved) and journal/NN_<short_name>.md. Then STOP.
  BLOCKED: sibling fetch. Do not offer "paste 2–3 paragraphs".
  Do not offer "confirm fetch". Do not run the three-branch ask.
  

• 会话开始时要读取 JOURNAL.md，而不是临时编造。 不要根据 experiments/ 文件名或 git log 重建历史——这些并不包含其中的 原因。

• 策略需要明确选择，不能想当然。 每份提案都要注明来源策略（skore / user / my-pick / B<N>）。不要默认为某种策略。例外：初始化——基线由工作区默认设置强制指定；无需派发策略选择。

• 批准必须明确。 用户说“approved” / “yes” / “go” / “looks good”才算通过关卡。含糊不清时 → 通过 AskUserQuestion 重新询问。

• 记录结果，不要只叙述。 运行结束时，必须先将结果写入 JOURNAL.md 和 Status 区块，再继续对话。

• 确保先前的实验仍可复现。 每个 done 行都必须能在 main 上运行，并产生相同结果。修改 src/<pkg>/ 时，默认行为应保留先前实验的结构（参见 build-ml-pipeline § Reproducibility）。快速检查：tests/smoke/——任何先前的冒烟测试失败，都意味着默认行为已被破坏。

• 在 src/<pkg>/ 中编写任何代码之前，必须按顺序使用三项技能。 G-DESIGN 之后：

  1. build-ml-pipeline → pipeline.py / features.py / data.py。
  2. evaluate-ml-pipeline → evaluate.py。该技能通过 AskUserQuestion 决定交叉验证策略。编写 evaluate.py 却不调用它，是最常见的捷径。
  3. test-ml-pipeline → smoke-test-ml-pipeline → 冒烟测试。

  只有完成这些步骤后，才能组装 experiments/NN_*.py。如果用户要求先编写 evaluate.py，而 pipeline.py / features.py / data.py 仍缺失，仍须从第 1 个环节开始： build-ml-pipeline。不要接着派发 evaluate-ml-pipeline。

• Harness 中“无需澄清问题”的提示不会免除关卡要求。 G-DESIGN、G-RUN、第 §1 节的模式选择（除非开场消息已确定迭代提案模式）、第 §2 节的来源菜单、第 §0 节的配置关卡，都是操作契约关卡。

• 事后审计——结束本轮前必须完成。 逐项检查所有预检行；明确指出未填写的 Evidence 单元格。

禁止走捷径

捷径	为什么不对
用户说“快速基线” → 跳过 G-DESIGN	G-DESIGN 不可妥协；“快速”／“标准”／“跳过设计说明”／“跳过问题”都不能免除这一步。本轮：拒绝，并仅起草 journal/01_baseline.md。不创建 experiments/01_baseline.py
用户说“跳过问题”／“标准表格数据” → G-EDA = 跳过	G-EDA 是由 explore-ml-data 负责的结构化运行／跳过流程。“跳过问题”“标准表格数据”和“快速基线”都不会设定为跳过。发出运行／跳过询问。只有明确表示“跳过 EDA”（或提供同级技能的跳过答复）才会记录 Status: skipped。
在 G-DESIGN 前于同一轮中搭建脚手架并实现	这颠倒了约定。未经批准就提交的代码，没有用户认可的动机／风险
因为 KFold(5)“感觉合适”而跳过 evaluate-ml-pipeline	即使 split_kwargs 为空，也是一项有依据的选择，而这正是该技能要让用户了解的。绕过它，用户就没有机会作出选择。拒绝写入。如果缺少 src/<pkg>/{pipeline,features,data}.py，本轮应调用 build-ml-pipeline，而不是等到下一轮调用 evaluate-ml-pipeline。
引导模式 → 跳过所有问题，而不只是数据源菜单	引导模式只禁止数据源菜单。仍须执行 G-PKG-NAME / G-ENV-MGR / G-TABULAR / G-SKORE-MODE / G-EDA / G-DESIGN / G-CV-SPLITTER / G-RUN
将含糊的“嗯，有意思”／“我想是吧”解读为批准	批准必须明确。遇到含糊答复 → 再次询问，绝不默认为同意
通过 reports/ 的修改时间自动检测运行已完成	§ 4 由用户触发（v1）。该技能绝不自动记录
§ 4 完成记录 → 宣布完成并跳过审计调用	§ 4 的审计调用属于记录结果流程的一部分，不是可选项。审计摘要会为 JOURNAL 行提供关键指标
在执行 G-RUN 的同一轮运行实验 → 不执行 § 4 就宣布完成	运行成功完成后，应在同一轮中于 G-RUN 之后执行 § 4。不要停在“我运行了”——记录结果
会话开始时预先阅读每个同级 SKILL.md 文件	读取集跟踪器不是阻塞关卡。按需打开同级文件；发出待处理列表，但继续进行

预检 — 任何设计说明写入前都要发出

简明清单；证据格式规范见 references/preflight_evidence.md。

Pre-flight (iterate-ml-experiment):
- [ ] `journal/JOURNAL.md` read this turn (or confirmed missing → bootstrap)
      Evidence: Read journal/JOURNAL.md (this turn) | "missing — bootstrap"
- [ ] `Workspace decisions` block checked for pre-recorded gates
      Evidence: lists each <gate>: <value | not recorded>
- [ ] Mode: bootstrap | iterate-propose | iterate-record |
      overview | compare | goal-pivot | abandoned | re-run
      Evidence: rule that matched (Mode picker row)
- [ ] Last experiment + status: <NN_name> | n/a — bootstrap
      Evidence: last row of JOURNAL.md History
- [ ] (Iterate-propose only) Sourcing menu presented; user picked
      Evidence: AskUserQuestion id=<id>, answer=<skore|user|my-pick|B<N>>
                | user free-text quote turn N
                | "n/a — bootstrap / read-only mode"
- [ ] (Bootstrap only) Upfront config gates fired (G-PKG-NAME,
      G-ENV-MGR, G-TABULAR, G-SKORE-MODE)
      Evidence: per-gate ask id OR JOURNAL.md Status reference
                | "n/a — iterate mode"
      Note: G-CV-SPLITTER is NOT an upfront gate — it fires later, in
      the § 3 chain at the evaluation step (after G-DESIGN).
- [ ] (Bootstrap only) G-EDA fired BEFORE the baseline draft
      Evidence: explore-ml-data dispatched; answer=<run|skip>;
                JOURNAL.md `## Data understanding (EDA)` section present
                | "n/a — iterate mode"
      "skip the questions" / "standard tabular" / "quick baseline"
      is NOT G-EDA = skip.
- [ ] Design note drafted (or Backlog enriched, for `skore`)
      Evidence: Write journal/<NN>_<name>.md (this turn) | "Backlog
                rows B<x>..B<y> appended" | "n/a — read-only mode"
- [ ] G-DESIGN: user approved before any `experiments/NN_*.py` touched
      Evidence: AskUserQuestion id=<id>, answer=approved | user quote |
                "n/a"
- [ ] (§ 3 only) Three-skill chain ran in order:
      `build-ml-pipeline` → `evaluate-ml-pipeline` → `test-ml-pipeline`
      Evidence: each owning skill produced its file this turn
                | "n/a outside § 3"
                | "BLOCKED — start at build-ml-pipeline (src files missing)"
- [ ] (§ 3 only) G-CV-SPLITTER resolved during the evaluate step
      Evidence: evaluate-ml-pipeline fired the splitter AskUserQuestion
                (or mapped split_kwargs) before `evaluate.py` write
                | "n/a outside § 3"
- [ ] (§ 3 only) G-RUN resolved: run now | leave for later
      Evidence: AskUserQuestion id=<id> | "n/a outside § 3"
- [ ] (§ 4 only) All artifacts written: Status block + JOURNAL row +
      Backlog hygiene + audit dispatch
      Evidence: list each artifact written | "n/a outside § 4"
- [ ] python-api consulted for any new external symbol
      Evidence: Read/Write scratch/api/<lib>/<v>/<topic>.md (this turn)
                | "n/a — only re-using cached symbols"
- [ ] Pre-flight re-emitted with evidence before final message.
      Evidence: this checklist appears in the end-of-turn summary.

§ 0 Bootstrap（仅首次会话）

当 journal/JOURNAL.md 缺失、是占位文件或没有任何历史记录行时，工作区处于引导模式。

流程（精简版 — 完整版本见 references/bootstrap.md）：

第一步： 先阅读 data/README.md，以此确定目标默认值，然后再询问用户。

1. 如有需要，先搭建脚手架。 如果没有 src/ / experiments/ / journal/ → 移交给 organize-ml-workspace，待占位文件 JOURNAL.md 存在后再返回。
2. 根据 templates/JOURNAL.md 重写 JOURNAL.md。
3. 先根据 data/README.md 推导目标默认值，再询问。提出一个句子；由用户确认或修改。
4. 在设计模型之前先探索数据（G-EDA）。 调用 explore-ml-data。此处只有两种选择（运行 / 跳过）；选择运行时，会执行 data/eda.py、写入 data/eda.md 和 HTML，并填充 JOURNAL 中的 ## Data understanding (EDA) 部分。发现结果（目标变量的分布是否均衡／偏斜、日期时间／分组列、缺失值情况、基数）会为下一步的学习器和指标默认值提供依据，并影响评估步骤稍后选择的交叉验证策略。运行路径需要 Agent 功能（ipython），因此此处、基线之前可能触发 G-AGENT-FEATURE；如果用户拒绝，则 EDA 改为跳过。跳过时，JOURNAL 部分记录 Status: skipped。不要因为用户说“跳过问题”“标准表格数据”或“快速基线”就设置为跳过——这些表达拒绝的是 G-DESIGN，并非回答 G-EDA。提出运行／跳过的问题。
5. 通过咨询链自动起草 journal/01_baseline.md，并结合 EDA 发现：学习器默认值（build-ml-pipeline）和指标默认值（基于 skore.evaluate 的 python-api）。此处不要确定拆分器——交叉验证策略由数据决定，应在评估步骤（G-CV-SPLITTER，由 evaluate-ml-pipeline 负责）确定，届时流水线的 X 标记已存在；记录中只需说明届时再决定。若与 EDA 发现或目标冲突，须在风险中标出，不要强行覆盖。
6. 用户在引导过程中的职责是批准或修改，而不是凭空设定。
7. 基线获批并记录后，即退出引导模式。 审计文件会在首次 § 4 结果记录时生成。

Bootstrap 会跳过数据源选择菜单——不会跳过配置门禁

已跳过：数据源选择菜单、第 § 1 节中的恢复／记录／提议选择。

仍会触发：

门禁 ID	选择项	负责方	触发时机
G-PKG-NAME	src/<pkg>/ 导入名称	organize-ml-workspace	创建清单文件之前
G-ENV-MGR	环境管理器	python-env-manager	执行任何安装命令之前
G-TABULAR	表格数据处理库（pandas / polars）	data-science-python-stack	写入 data.py 之前
G-SKORE-MODE	Skore Project 模式（local / hub / mlflow）+ hub 工作区名称或 MLflow 跟踪 URI	organize-ml-workspace	写入 pyproject.toml 之前
G-EDA	探索数据（运行／跳过），在设计基线之前	explore-ml-data	起草 journal/01_baseline.md 之前
G-AGENT-FEATURE	安装 ipython + pyright（安装／跳过）	python-env-manager	有条件触发——当 G-EDA = run 且尚未启用 Agent 功能时（否则在第 § 4 节首次审查）
G-DESIGN	用户批准 journal/01_baseline.md	此技能	编写任何 src/<pkg>/ 或 experiments/ 代码之前——即第 § 3 节链条之前
G-CV-SPLITTER	skore.evaluate 的交叉验证系列	evaluate-ml-pipeline	在第 § 3 节链条中，G-DESIGN 之后——在评估步骤中、写入 evaluate.py 之前；即使 split_kwargs 为空也必须设置
G-RUN	“现在运行”还是“留待以后”	此技能	执行实验脚本之前

自由文本“快速基线”／“标准表格数据”／“跳过问题”／“你来选” 不会解决上述任何门禁——包括 G-EDA。改用结构化的 AskUserQuestion。只有明确回答“跳过 EDA”或在 explore-ml-data 中选择跳过，才会记录 G-EDA = skip。

→ 下一步：G-DESIGN，然后进入第 § 3 节实现链条。

§ 1 会话开始（迭代模式）

• 阅读 JOURNAL.md。
• 用 2–3 行向用户总结：数据集、目标、最近一次实验及其状态、Backlog 中目前适合处理的事项。

**如果开场消息已经是 iterate-propose，则跳过三选一询问。**符合条件的信号包括：“下一步做什么？”、“提议下一步”、“我们继续迭代”，且 History 中至少有 1 行已完成记录。模式选择器已经确定了路径——本轮直接进入第 § 2 节（数据源选择菜单）。不要停下来询问恢复 | 记录结果 | 提议下一步。

否则，通过 AskUserQuestion 询问——提供三个选项，不设默认选项：

• 恢复——最近一次实验仍处于计划中／已批准／未完成状态。
• 记录结果——最近一次实验已经运行；进入第 § 4 节。
• 提议下一步——最近一次实验的状态为 done 或 abandoned；→ 第 § 2 节。

自由文本“继续吧”／“好啊”含义不明确——等待明确答复。

§ 2 提议下一次实验

数据源选择菜单——原样呈现

在迭代模式下，每次执行第 § 2 节时，都要和 JOURNAL.md 的 Backlog 表一起呈现此菜单。绝不默默使用默认选项。

**已明确的选择会完全跳过菜单。**如果用户的开场消息已经指出策略——一个 URL、一个 B<N>、明确的“我选这个”——则第 § 2 节已满足要求，不再显示菜单。即使是“留个记录”、“提高透明度”、“让你看看我跳过了什么”或放进折叠块，也不应再次复现菜单，因为这仍然是在呈现菜单：读者会看到四个选项和一个提示。只需说明输入对应的分支，然后继续。

How would you like me to source the next experiment?

  skore    — read the audit digest at scratch/audit/<stem>/audit.md
             from the latest run; follow each surfaced check's
             documentation_url to draft a Backlog row, summarize,
             re-present this menu.
  user     — you tell me what to try: article URL, GitHub issue,
             spec / reference repo, or free text.
  my-pick  — I synthesize 2–4 candidate ideas; you pick one.
  B<N>     — promote a Backlog row directly.

Backlog (pick by index):
<paste JOURNAL.md Backlog table here>

使用 AskUserQuestion 让用户选择，或者以“我会请你选择”／Your pick? 结尾。只有在结构化界面不可用时，才使用纯文本列举。始终在四个选项旁标出 Backlog 索引（B1、B2、……），即使没有粘贴各行内容也一样。

自由文本处理——优先匹配

用户说……	解析为
完全匹配的标签（skore / user / my-pick / B<N>）	对应选项
B2 / “就选 B2”	B<N> 选项
粘贴了科学文章 URL	user → 文章链接分支
GitHub issue URL / org/repo#N / 规范路径	user → 资源链接分支。预先解析后分发 iterate-from-user。不要询问摘要。不要再次展示来源菜单。设计说明路径：journal/NN_<short_name>.md。
“给我一些想法” / “你来决定”	my-pick
“让我试试 X” / “改用 Y”	user → 自由文本分支
含糊不清 / 不在菜单中	调用 AskUserQuestion，不要猜测

分支

• skore → 分发至 iterate-from-skore。返回 待办候选行 + 摘要。为行添加稳定的 B<N>， 显示摘要，再次展示来源菜单。本轮不写设计说明。
• user → 分发至 iterate-from-user。返回一份提案。 起草至 journal/NN_short_name.md。
• my-pick → 行内处理。读取 JOURNAL.md 中的 Status、最近的 Implication / Risks 和当前 Backlog。综合出 2–4 个候选项， 通过 AskUserQuestion 呈现。选定后起草设计说明。
• B<N> → 提升该行。该行的 Item 成为种子； 该行的 Source 成为 Sourcing strategy。获批后从 Backlog 中移除。

对于 user / my-pick / B<N>：使用 templates/experiment_design.md 将草稿写入 journal/NN_short_name.md。NN 是下一个可用整数；short_name 是用户指定的名称。

→ 下一步：§ 3。

§ 3 迭代设计说明并实现

• 显示草稿：文件路径 + 3–5 行摘要 （Question / Method / Risks）。

• 迭代中途的反馈使用自由文本。 原地编辑 journal/NN_*.md， 并在此循环。

• 最终审批关卡必须使用 AskUserQuestion，提供两个选项：

  • approved — 更新状态，添加 JOURNAL History 行，并交接 给三技能链。
  • more changes — 返回修改循环。

  清晰的自由文本“approved” / “go” / “looks good”即视为通过； 含糊不清时 → 使用结构化提问。

• 设计迭代期间不要创建 experiments/NN_*.py。

• 如实记录来源。 仅修改 Risks 时保留原有的 Sourcing strategy。修改 Method 时 → <original> + user override。

三技能实现链——不可跳过

通过 G-DESIGN 后，按顺序分发：

1. build-ml-pipeline → src/<pkg>/{pipeline,features,data}.py。
2. evaluate-ml-pipeline → src/<pkg>/evaluate.py。通过 AskUserQuestion 负责确定 CV 策略。绕过此步骤是明确禁止的捷径。
3. test-ml-pipeline → smoke-test-ml-pipeline → 在 tests/smoke/test_NN_<short_name>.py 中编写对应的冒烟测试。

只有完成这些步骤后，才能组装 experiments/NN_*.py。通过 python-api 而不是凭记忆确认签名。

如果用户只要求编写 evaluate.py（即使已经指定了 splitter），且 缺少 pipeline.py / features.py / data.py：拒绝编写，指出这条链： build-ml-pipeline → evaluate-ml-pipeline → test-ml-pipeline， 并首先调用 build-ml-pipeline。第 2 步必须等第 1 步 返回后再进行；不要说“下一步分发 evaluate-ml-pipeline”。

G-RUN — 冒烟测试后的运行关卡

当 tests/smoke/ 通过（新测试和所有之前的测试都通过）后： 通过 AskUserQuestion 询问：

• run now — 执行 pixi run python experiments/NN_<short_name>.py。
• leave for later — 不要打印命令，不要自动提议。原样显示 JOURNAL Status + Backlog，然后停止。

不要静默默认。

→ 下一步：如果本轮运行已完成，立即继续至 § 4。不要止步于“我运行了”——记录结果。

§ 4 记录结果

触发条件：用户说“运行结束了” / “记下来”，或者 Agent 在同一轮中运行实验（G-RUN = run now）且成功完成。不要通过 reports/ 的修改时间自动检测，也不要轮询用户自行启动的运行。

流程

1. 审计优先：派发给 audit-ml-pipeline，以放置并执行 audit/NN_<short_name>.py。审计会通过随附的运行器以只读方式读取报告，并输出包含关键指标的 Markdown 摘要。审计会取代临时探查——如果审计是规范路径，就不要编写 scratch/<ts>_inspect_*.py 从报告中提取指标。
   • 必须安装 Agent 功能；如果未安装，audit-ml-pipeline 会路由至 python-env-manager § Agent 功能（G-AGENT-FEATURE）。
2. 阅读审计摘要。指标和检查摘要是接下来 3 个步骤的信息来源。
3. 填写 journal/NN_*.md 中 Status 块的全部四个字段：
   • State：done（或 abandoned，并附上一行原因）。
   • Approved by user on：保持与批准时一致。
   • Headline result：逐字复制用户（或审计）提供的指标。不要编造额外数字、折数或他们未提及的残差结论。如果他们已经说过 0.081 ± 0.005 on 5-fold CV，就可以使用这句话。
   • Implication for next iteration：1–2 句话。
4. 标记为 done 前通过 Smoke 测试门槛——tests/smoke/ 中的所有测试都必须通过。先前的失败意味着可复现性回归 → 路由至 build-ml-pipeline § 可复现性。CV 报告仍可写入 skore Project，但在完整 smoke 套件通过前，JOURNAL 行必须保持 approved。放弃实验无需通过 smoke 测试。
5. 将关键结果追加到 JOURNAL.md 的 History 中。
6. 清理 Backlog：检查新一轮实验已回答或淘汰的事项。删除，或使用删除线标记（~~old~~ — resolved in NN_X）。对新报告进行诊断挖掘是 iterate-from-skore 的工作，不属于 § 4。
7. （可选）通过 GitHub issue 形成闭环——如果实验的 Source 是 GitHub issue，通过 AskUserQuestion 询问是否要使用关键结果执行 gh issue comment <N>。绝不自动发布。

到此为止。同一轮中不要自动提出下一个实验。 结束时通过 AskUserQuestion 逐字给出以下两个选项：

• 现在起草 — 将推论作为种子，重新进入 § 1。
• 暂不 — 将推论记录到 Backlog，然后停止。

列出这两个选项不等于提出下一个实验。自动提出意味着在本轮中编写下一份设计说明或实验正文。由用户掌控节奏；此技能负责记录，不会在同一轮中一边提出一边记录。

派发对照表 — 使用哪个 iterate-from-* 技能

情况	操作
没有先前实验（引导启动）	§ 0 强制自动起草基线。不使用策略技能
用户指定了 Backlog 行（B2、“我们做 B5 吧”）	直接提升；不使用策略技能
“挖掘报告” / “skore 看到了什么？”	iterate-from-skore — 丰富 Backlog，并重新展示菜单。本轮不写设计说明。
“我想试试 X” / 文章 URL / GitHub issue	iterate-from-user。GitHub issue URL / org/repo#N：传入预先解析的（resource-link）。不要触发三分支询问。不要要求用户粘贴 issue 正文。目标位置为 journal/NN_<short_name>.md（NN = 下一个 History 索引）。只有在 Proposal 返回后才起草。
“给我一些想法” / “你来决定”	my-pick — 在当前流程中处理。综合 2–4 个候选项，通过 AskUserQuestion 询问
至少已有 1 个已记录实验，用户开放式地问“下一步做什么？”	逐字展示来源菜单和 Backlog。不静默采用默认选项

策略技能刻意保持浅层：它们负责提供来源，此技能负责起草。skore 策略要求先前已有一项带有磁盘报告的实验——引导启动时不能使用它。

如果 iterate-from-skore 返回零个候选项：在 JOURNAL Status 中追加一行（Audit checks clean on <stem> as of <date> 或 Audit digest inaccessible on <stem> as of <date>）。不要添加 History 行。重新展示来源菜单。

维护模式 — 参考

这些模式均为只读或极少使用。完整流程见 references/maintenance_modes.md：

• 项目概览 — 从 JOURNAL + Backlog 生成的只读摘要。 不要生成单独的文档。
• 比较以往实验 — 只读。v1 是基于 JOURNAL.md History 进行的成对并排比较。不要起草设计说明。 不要添加 JOURNAL 行。本轮：仅比较表。 不要添加“建议的 后续步骤”，也不要分派给 audit-ml-pipeline / iterate-from-skore。下一项实验留待 后续用户轮次。
• 目标转向 — 使用日期 + 原因更新 Status，在 History 中插入 水平分隔线，并在下一项实验的 Risks 中标明不可比较性。
• 放弃实验 — AskUserQuestion（abandon / defer / run now）。Status 变为 abandoned，并附上一行原因。
• 重新运行 — 单项（NN_<stem>_rerun）或批量 （NN_paired_comparison）。创建新的设计说明；原有说明 保持不变。

此技能负责的文件

journal/
├── JOURNAL.md                # status + history + backlog (index)
├── 01_baseline.md            # design note for experiments/01_baseline.py
├── 02_<short_name>.md
└── …

配对规则（严格，四项配套）：journal/NN_<short_name>.md ↔ experiments/NN_<short_name>.py ↔ tests/smoke/test_NN_<short_name>.py ↔ audit/NN_<short_name>.py，文件名主体必须相同，且一一对应。

JOURNAL.md 结构

1. Status — 2-3 行：数据集、目标、最近一项实验 + 状态。
2. Data understanding (EDA) — 简短摘要 + 指向 data/eda.md 的链接。由 explore-ml-data 负责（在 G-EDA 引导步骤中撰写）；此技能仅保留该章节。
3. History（按时间顺序）— 每项实验占一行：文件名主体、 意图、状态、核心结果、设计说明链接。
4. Backlog（前瞻性）— 带索引的表格；列为 #、 Item、Source（skore:<stem> / my-pick:<stem> / user）。

模板：templates/JOURNAL.md。这四个是唯一获准的 章节——不要另行创建章节。

每项实验设计说明的结构

模板：templates/experiment_design.md。章节：

• Question / hypothesis — 一句话。
• Motivation — 从信息来源策略中提取；引用具体内容。
• Method — 用文字说明相较上一项实验的改动。具体机制由 build-ml-pipeline / evaluate-ml-pipeline 负责。
• Risks — 哪些因素会导致指标因错误原因而变化。
• Status block — planned → approved → done | abandoned。

不要添加“Success criteria”章节。 由用户在运行后评判。

此技能不负责的事项

• 运行实验（由用户 / runner 负责）。
• 探索 / 分析数据集（explore-ml-data 负责 G-EDA 步骤和 ## Data understanding (EDA) 章节）。
• 打开或查询 skore Project（由 evaluate-ml-pipeline + python-api 负责）。
• 编辑 pipeline.py / features.py / data.py （由 build-ml-pipeline 负责）。
• 判断工作区是否存在或文件应放在哪里 （由 organize-ml-workspace 负责）。
• 编写提交 / PR。
• 定义什么样的实验算成功。
• 代替用户选择信息来源策略。

配套技能

技能	关系
organize-ml-workspace	搭建脚手架 + 文件名主体配对规则
explore-ml-data	§ 0 会在基线实验前触发 G-EDA；EDA 发现会为基线说明的 Method / Risks 以及 ## Data understanding (EDA) JOURNAL 章节提供依据
iterate-from-user	来自用户的信息来源提案（文章 / 资源 / 自由文本）
iterate-from-skore	根据报告补充 Backlog
build-ml-pipeline	pipeline.py / features.py / data.py 主体；可复现性机制
evaluate-ml-pipeline	evaluate.py 主体；CV 策略决策；报告检查
test-ml-pipeline → smoke-test-ml-pipeline	Smoke 测试主体；§ 4 只有在 Smoke 测试通过后才会将状态设为 done
audit-ml-pipeline	§ 4 分派；审计摘要包含 JOURNAL 行所需的核心指标
python-api	签名查询
python-env-manager	audit 和 explore-ml-data（EDA）前置条件所需的 G-AGENT-FEATURE

参考资料（按需加载）

• references/bootstrap.md — 完整的引导流程、config-gate 详情、基线模板替换。
• references/record_outcome.md — 完整的 § 4 流程，包括 Backlog 卫生示例、GitHub 评论模板。
• references/maintenance_modes.md — 概览／比较／目标调整／放弃／重跑，以及完整流程。
• references/preflight_evidence.md — 证据格式规范。

模板

• templates/JOURNAL.md — 四节索引骨架。
• templates/experiment_design.md — 带有 Status 块的设计说明。

复制，不要重写。