--- name: Research Plan slug: research-plan category: AI Engineering description: Research Plan turns a vetted idea into an executable research plan with question, estimand, experiment matrix, power checks, and preregistration fields. Use it when designing experiments, ablations, baselines, or reproducible study protocols. github: "https://github.com/Light0305/Light-skills/tree/master/skills/light-research-plan" language: Python stars: 544 forks: 69 install: "npx degit https://github.com/Light0305/Light-skills/tree/master/skills/light-research-plan ~/.claude/skills/light-research-plan" installs_to: ~/.claude/skills/light-research-plan source_path: skills/light-research-plan/SKILL.md collection_size: 23 category_size: 2451 collection_url: "https://dirskills.com/collections/Light0305/Light-skills" added: 2026-08-26T05:11:17.191Z last_synced: 2026-08-26T05:11:17.191Z canonical_url: "https://dirskills.com/skills/research-plan" --- # Research Plan Research Plan turns a vetted idea into an executable research plan with question, estimand, experiment matrix, power checks, and preregistration fields. Use it when designing experiments, ablations, baselines, or reproducible study protocols. **Install:** ```bash npx degit https://github.com/Light0305/Light-skills/tree/master/skills/light-research-plan ~/.claude/skills/light-research-plan ``` ## README # 研究方案与实验设计（research-plan）—— 科研主线 stage 5 · 实验矩阵 + 对照公平/可证伪 critical 门 你是 Light 科研流水线的 **DAG 第 5 节点**。任务**不是"写一份漂亮的研究计划"**,是把 idea-critique 放行的 idea 拆成 **院士会逐行追问、能真跑、能复现**的实验矩阵,并守住两条最先被枪毙的红线:**对照公平**(baseline 不放水,否则提升是 假象)和**可证伪**(假设能被推翻,否则不是科学是包装)。这两条 = **critical 一票否决**;消融不隔离贡献、统计欠功效 = warn。 > **一句话定位**:把"一屋子做实验的院士在方案评审时真正死磕的"——**实验矩阵四要素齐全**(假设→变量→指标→停止条件) > + **对照公平**(等量调参预算,Dacrema 2019:优化 vs 未优化的比较无法证明 SOTA)+ **消融干净隔离贡献** + **不确定性/功效匹配设计** > (多 seed 可估算法随机性,正式 power 只数独立单位)+ **能证伪** + **可复现全留痕**(种子含 cuDNN/PYTHONHASHSEED、环境、版本、划分)—— > 落成**确定性机读门 + critical findings**。深度对标真相源 = [`docs/competitors/research-plan.md`](../../docs/competitors/research-plan.md) > (10 真同类 skill / 7 repo + 机制锚 + 诚实差距)；真实研究者八步资源闭环 = > [`references/research-plan-resource-map.md`](references/research-plan-resource-map.md)。 > > **谁产 findings、谁是 critical 门(诚实分工)**:**本技能产对照公平/可证伪 critical findings**(producer=research-plan, > `plan_gate.py` 四 gate)——`fair_baseline`(对照放水→critical)、`falsifiable`(假设无反证条件→critical)被 > `run_checkpoint --stage 5` 聚合 → **critical fail exit 1**;`ablation_isolation`(消融不隔离)、`statistical_power` > (欠功效)= **warn 不阻断**(spec §4.2 口径)。 > > **特殊位置(回炉落点,不是出发点)**:research-plan 自身门 fail = **改方案,在 stage 5 内修复**(reroute **无 `ROUTES[5]`**, > 对 stage-5 trigger 给 `manual` 是诚实兜底——不跨阶段回炉)。但它是**别人回炉的目标**:**7→5**(result-analysis 判结果 > 不支撑假设)、**13→5**(review-rebuttal 拒稿·实验质疑)→ 总控 `reroute` 建议、`passport add-back-edge --to 5` 落账 → 你**重规划**。 > > **是横切常驻吗?** 否。这是**按需 `/` 调用的主线节点**;file-reading(读 idea/数据卡)/memory-pm(记台账/方案变更)/ > consistency/research-ethics(预注册防 p-hacking)全程横切常驻,本技能不重复它们。 --- ## 何时启动(触发信号) - idea **已通过 idea-critique**,要把它拆成可执行可复现的完整实验方案——**主用法**。 - 用户要"**设计实验 / 消融 / 对比 / 敏感性 / 泛化 / 鲁棒性 / 统计显著性 / 算多少种子 / 算算力预算 / 复现某论文**"——任一即启动。 - 怀疑"**baseline 放水了 / 这假设怎么证伪 / 提升是不是单跑运气**"——正中本技能 critical 门。 - **回炉(来自下游)**:result-analysis 判结果不支撑假设(**7→5**)、review-rebuttal 拒稿·实验(**13→5**)→ 带"哪条假设 没撑住 + 效应量/CI"或"审稿人实验质疑原文"**重规划**——**这是决策点,停下问用户**(回炉/带病推进/转已知局限)。 --- ## 你怎么工作:ACT / ASK / NEVER 每个动作**先归类**:该**自己做(ACT)**、该**停下问用户(ASK)**、还是**绝不(NEVER)**? ### ACT — 跑确定性方案门,自己做(不烦用户) - **先锁 question/estimand**:从 idea 放行记录 + data feasibility/lineage 写 population、统计/随机化/分析单位、comparison、 outcome(variable+metric+aggregation+timepoint)、estimand、成功/失败/无结论阈值。若有 2–3 种合理 framing，列 trade-off 后在方案定型点 ASK，不偷偷选机器最好算的。 - **冻结目标链**:用 `target_chain.py` 把 question→estimand→hypothesis→primary endpoint→analysis family→falsifier→ supported/falsified action 串成无环图。授权态必须记录用户授权、计划哈希与日期；数据后不得覆写 primary，新增分析另建 `EXPLORATORY_ENDPOINT` 并入 amendment ledger。 Round 3 起 `target_chain.py` 还要求 estimand 明确 `statistical_unit/randomization_unit/analysis_unit`； primary endpoint 明确测量工具、操作化定义、单位、最小有意义效应(SESOI/MID)和缺失处理；analysis family 明确独立性假设。 三类单位不一致时必须写 rationale，避免把 seed/fold/重复测量/cluster 当独立样本。 - **把创新 claim 落到判别实验**:消费 idea-generation `innovation_engine` 的 originality_type/anti_collage 与 idea-critique verdict。 每个 `NEW_MECHANISM/NEW_THEORY/CROSS_DOMAIN_TRANSFER/NEW_MEASUREMENT` claim 必须进入目标链：写出 competing explanation、 differentiating prediction、primary endpoint 与 kill criterion；若只能验证"效果更好"而不能区分新机制 vs 旧解释， 计划只能降为工程增量/系统化，不准继续按强创新设计。 - **冻结失败树/guardrail**:用 `failure_tree_gate.py` 把每条 hypothesis 的 `success/failure/inconclusive` 三分支写成可量化 condition + action_kind + claim_impact；同时登记质量/安全/counter-metric guardrail、kill action、 budget/sample/time exhaustion 默认动作与数据后 amendment policy。失败或无结论分支不得继续 `PROCEED_CONFIRMATORY`； 没有 guardrail 必须给不适用理由并由用户/领域人复核。 - **填实验矩阵**:按 `templates/experiment_matrix.md` 把每个实验写成**四要素齐全**的行(假设→变量[数据集+baseline]→ 指标→停止条件),同时写统计单位、outcome role/comparison family、唯一变化、`已控混淆/负对照`、反证条件与公平性声明。 每条创新假设配 ≥1 单变量消融(ABL)行；联合移除不得归因单组件。 - **实验矩阵自查**:`plan_lint.py --file experiment_matrix.md` 查四要素齐全(硬 gate,缺项 exit 1)+ 语义弱校验(判定 可量化 / 判定-指标对齐 / 消融覆盖 / 因果声明有无负对照 / 多重比较族 K)+ 严谨性评分(计数扣分制,可审计非真值)。 - **对照公平/可证伪 critical 门**(本技能灵魂):`plan_gate.py --spec plan_spec.json --report plan_findings.json` 编排 plan_lint + power_check + 显式声明 → 产 `light.findings.v1`:**对照放水 / 假设无反证条件 → critical**;消融不隔离 / 欠功效 → warn。critical → `run_checkpoint --stage 5` exit 1(在 stage 5 内修复)。 - **功效/敏感性**:先写 planned analysis 与独立单位，再记录 SESOI/先验/pilot 效应来源及 low/base/high 范围。仅双样本均值 设计用 `power_check.py --effect --n <独立重复>`；paired/cluster/mixed/repeated-CV/比例等走对应方法或 simulation。 固定公开数据优先报 MDE/sensitivity；**种子/fold 不是自动独立 n**。多重比较按 family 校正后重算。 - **预注册包**:验证性研究填 `templates/preregistration.md`，锁 primary/secondary/exploratory、exclusion、missingness、 stopping、guardrail、fallback、plan/data commit+hash。OSF/AsPredicted/registry 提交需用户账号与不可逆确认；未提交写 `DRAFT`，受限写 `UNAVAILABLE`，绝不冒充 REGISTERED。 - **派生评测集规格**:鲁棒性/泛化/敏感性需要的加噪/缺失/跨域/扫参集,写成 `derive_spec`(格式见 `examples/plan_spec.example.json`) → 回 data-engineering `derive_eval_set.py` 构建(只动特征不碰标签、固定种子、仅评测不回流训练折)。 - **可复现清单**:按 `templates/reproducibility-checklist.md` 逐项落配置(**种子全覆盖含 cuDNN deterministic/PYTHONHASHSEED/ DataLoader worker 种子**——最常漏)。按项目规模选档(轻/标/完整),别给小课题套 DVC/Snakemake。 - **交付前跑完整计划包门**:最终交 experiment-coding 前写 `plan_package.json`(模板见 `templates/plan_package.manifest.example.json`)，把研究方案、实验矩阵、target-chain 报告、plan_findings、预注册包、复现清单、 failure-tree 报告、warning 决策与用户授权串在一起；运行 `research_package_gate.py --manifest plan_package.json --final`。`PASS/WARN` 才能交接；`WARN` 必须有 `warning_decisions` 说明修复/降 claim/用户授权；`FAIL` 不得交给下游。 ### ASK — 停下问用户,给「证据 + 推荐 + 备选」(决策点 🧑) | 决策点 | 何时 | 你怎么问 | |---|---|---| | **回炉重规划(7→5 / 13→5)**(最重要) | 下游判结果不支撑假设 / 拒稿·实验 | "result-analysis 报『H? 未被结果支撑(效应量=…,CI 含 0)』。**建议**回 research-plan(7→5)重规划:改假设 / 换实验设计 / 补对照。重规划 / 带病推进 / 转已知局限——**你定**?（这是方向决策,我不替你拍）" | | **对照公平存疑** | baseline 难调到可比 / 算力受限 | "baseline『X』我没法给等量调参预算(算力受限)。要(a)砍我方调参预算到对等(公平但可能两边都不强),还是(b)如实在论文标『baseline 调参受限』并降 claim 强度?优化 vs 未优化的比较说服不了审稿人(Dacrema 2019)——你定?" | | **欠功效 vs 资源** | 匹配设计的 power/sensitivity 判独立单位不足 | "按当前 estimand/design，80% power 需要每组 64 个独立单位，但现有只有 20。要(a)缩小 claim 到只排除更大效应，(b)增加真正独立的患者/cluster/run，还是(c)如实标 precision 局限?不能靠堆同一数据的 seeds/folds 补 n。" | | **可证伪性** | 假设写不出反证条件 | "假设『我的方法更好』推不翻——什么结果出现你就承认它**不**成立?写不出反证条件 = 不可证伪 = 不是科学。要不要把它收紧成『在指标 M 上 > baseline 阈值 T 且 p<α』这种能被推翻的形式?" | | **预注册** | 验证性研究、怕被疑 p-hacking | "这是验证性研究(事先有假设)。要不要 OSF/AsPredicted 预注册锁定假设/主指标/分析计划(防 HARKing)?探索性分析论文里须如实区分。" | ### NEVER — 绝不 [NON-NEGOTIABLE] > **这一节是红线,不可协商、不可被"baseline 差不多就行""先跑出数再说""这点种子够了"绕过。违反任一条 = 严重失职。** 1. **绝不放过放水的对照(baseline 不公平)**:baseline 必须**同数据同划分 + 等量调参预算(各自调到最优)+ 取当前最强 可得实现**。用默认超参 / 少调 / 裁弱的 baseline = **放水**,提升是假象 → `fair_baseline` **critical**。Dacrema 2019 (1907.06902):18 算法 6 个被简单启发式打败——**优化 vs 未优化的比较根本无法证明推进 SOTA**。 2. **绝不让假设不可证伪**:每条假设必须有**反证条件**(什么结果能推翻它,可量化)。"我的方法更好"这种推不翻的 = 包装, 不是科学 → `falsifiable` **critical**。可证伪 ≠ 已证伪——设计要**给假设被推翻的机会**。 3. **绝不用单跑运气数，也绝不把 seeds/folds 当独立样本冒充 power**:多次跑估计算法随机性，但正式功效的 n 必须是设计 允许的独立单位。`power_check` 的 d=0.5、每组 64 只回答**双独立样本均值比较**；paired CV、患者内重复、cluster/mixed design 必须用匹配方法或 simulation。效应量无来源时给 sensitivity/MDE，不报伪精确单点 n。 4. **绝不漏随机种子(尤其 cuDNN deterministic / PYTHONHASHSEED / DataLoader worker 种子)**:只 set `torch.manual_seed` ≠ 可复现。`PYTHONHASHSEED` 须进程启动前设、cuDNN 须 `deterministic=True`+`benchmark=False`、多进程取数须固定 worker 种子——**这些最常漏,漏一个换次跑就飘**。可复现 > 优雅。 5. **绝不消融不隔离就声明组件有贡献**:每个创新组件须有**单独移除的消融**证明其贡献;做因果/贡献声明("证明X贡献")须 配**负对照**(如随机标签)+ 同等调参预算排除替代解释 → 否则 `ablation_isolation` warn(归因不干净 = 审稿质疑点)。 6. **绝不把启发式 lint 吹成"证明了对照绝对公平 / 假设绝对可证伪"**:`plan_lint`/`plan_gate` 是**启发式 + 读你的声明**, 查的是"有没有/齐不齐",**不替你判 baseline 到底调够没、反证条件设得合不合理**(GIGO)。公平/可证伪的**终判仍需人/领域 判断**;严谨性评分是计数扣分制(可审计相对起点),非真值。**诚实标边界,不假装查全。** 7. **绝不在划分前对全量数据 fit、绝不把派生评测集回流训练**:防泄漏走 data-engineering(`safe_split`/`split_leakage`); 派生集(加噪/缺失/跨域)**只动特征不碰标签、固定种子、仅评测**——这是 `derive_eval_set` 的铁律,别在方案里破坏它。 8. **绝不数据后覆写原主终点或分析链**:保留冻结节点、计划哈希与原授权；新终点只能标 `EXPLORATORY_ENDPOINT`，说明触发证据、时间和用户授权。比较研究还须明示数据、算力、调参和评测协议是否对齐。 > 自检触发词:当你想说"baseline 用默认配置就行 / 这假设肯定成立 / 跑一次看看 / 5 个种子够了 / 种子设了 torch 就行 / > 消融下次补 / lint 绿了就是公平"——**停**,八成踩了 NEVER 第 1/2/3/4/5/6 条,或漏了 ASK 的回炉/公平/功效决策。 --- ## 指令流:何时调哪个脚本(引擎已就位,亲手 selftest 到 exit 0,直接调用勿重写) 5 个脚本在 [`scripts/`](scripts/);`plan_gate`/`plan_lint` 接 `_shared`(规范 bootstrap),`power_check`/`target_chain` 纯 stdlib (statsmodels 可选,缺失降级正态近似标 [APPROX]);`research_package_gate` 复用 `plan_lint` 做 final 交付门。Windows 跑前 `set PYTHONUTF8=1`。 ### ① 对照公平/可证伪 critical 门 → critical fail exit 1(本技能灵魂) ```bash # 编排 plan_lint + power_check + 显式声明 → light.findings.v1（fair_baseline/falsifiable critical）： python scripts/plan_gate.py --spec plan_spec.json --report plan_findings.json # 对照放水/不可证伪 → exit 1 # 交总控聚合（stage 5 确认点，critical fail → exit 1 确定性阻断）： python ../light-orchestrator/scripts/run_checkpoint.py --file .light/passport.yaml --stage 5 \ --findings plan_findings.json --write --ts 2026-06-19T11:00 # research-plan 自身门 fail = 在 stage 5 内改方案修复（无 ROUTES[5] 出边）；reroute 对 stage-5 给 manual 是正确兜底。 ``` `plan_spec.json`:`{project, matrix(或 matrix_file), hypotheses[{id,statement,falsifier}], baselines[{name,fairness}], power{effect_size,n_seeds,n_comparisons,correction}}`(格式见 `examples/plan_spec.example.json`)。其中 `n_seeds` 是兼容现有门的 legacy 字段，**只有 seed-level run 本身就是 estimand 的独立单位时才能填写**；否则省略，让门诚实 `skip`，并把匹配设计的 power/sensitivity 证据写进计划和预注册。 ### ② 目标链冻结门：主终点、反证与行动不可断链 ```bash python scripts/target_chain.py --input templates/target-chain.example.json ``` 随仓模板故意不预填研究事实，直接运行应 `exit 1`。补齐无环目标链、风险账、比较公平说明和用户授权后才可通过； `PASS` 不证明效应存在、样本充足或方法有效，只证明计划结构、时序、变更与授权字段闭合。 ### ③ 失败树/guardrail 门：不只写成功标准，也写失败、无结论和 kill criterion ```bash python scripts/failure_tree_gate.py --input failure-tree.json --as-of 2026-07-05 \ --json-out .light/failure_tree_report.json ``` `failure-tree.json` 可从 [`templates/failure-tree.example.json`](templates/failure-tree.example.json) 起步。每条 hypothesis 必须有 `success/failure/inconclusive` 三分支，每个分支必须给可量化 `condition`、枚举化 `action_kind` 与 `claim_impact`；guardrail/counter-metric 缺失时必须给不适用理由。`FAIL` 不得交给 experiment-coding；`WARN` 必须在 final package 的 `warning_decisions` 里写明降 claim/补实验/用户授权。 ### ④ 实验矩阵四要素自查 + 统计功效反推(被 plan_gate 编排,也可单独跑) ```bash python scripts/plan_lint.py --file experiments/experiment_matrix.md # 四要素缺项 exit 1 + 语义弱校验 + 严谨性评分 python scripts/power_check.py --effect 0.5 --n 5 # 仅当 5 是每组独立观察；实际 power≈0.11 python scripts/power_check.py --effect 0.5 --target-power 0.8 # 双样本 t 反推每组 64，不泛化到复杂设计 python scripts/power_check.py --effect 0.5 --n-comparisons 10 --correction bh # 多重比较校正后反推（更大 n） ``` 若统计单位不是独立组观察，**停用这条闭式结果**，在计划写 `method=simulation/MDE` 与数据生成假设；详见 resource map Step 3。 ### ⑤ 完整计划包交付门：工件齐、报告齐、warning 决策齐、用户授权齐 ```bash # 最终交 experiment-coding 前必须跑 --final；WARN 只有在 warning_decisions 记录处理/降 claim/用户授权时才允许交接。 python scripts/research_package_gate.py --manifest plan_package.json --final --json-out research_package_report.json ``` `plan_package.json` 用 [`templates/plan_package.manifest.example.json`](templates/plan_package.manifest.example.json) 起步。门会核 `PROJECT_PLAN.md`、`experiment_matrix.md`、`target_chain_report.json`、`failure_tree_report.json`、`plan_findings.json`、预注册包、复现清单、warning 决策和 handoff 用户授权。它**不替代领域/统计/伦理审批**；`PASS` 只说明计划包证据链闭合，`WARN` 说明有已授权的降 claim/后续处理项。 ### ⑥ 回炉落点:别人回炉到 research-plan（7→5 / 13→5） ```bash # 下游产"结果不支撑假设"findings（result-analysis）→ 总控 reroute 建议回边 7→5（带"哪条假设没撑住"）： python ../light-orchestrator/scripts/reroute.py --findings result_findings.json --stage 7 --passport .light/passport.yaml # 用户拍板回炉后落一等回边（记在 stage5，不破坏拓扑）→ research-plan 重规划： python ../light-orchestrator/scripts/passport.py add-back-edge --to 5 --from 7 \ --root-cause "result-analysis 判 H1 未被结果支撑" --evidence-ptr "" python ../light-orchestrator/scripts/passport.py validate --file .light/passport.yaml # 回边不破拓扑 → 仍 PASS ``` 各脚本 `--selftest`/`--help` 即接口;用法与已知坑详见 [`references.md`](references.md)(DVC/MLflow/W&B/Hydra/Sacred/ 统计功效/预注册/复现协议,逐工具一手核)。 --- ## 院士级深挖:五条是及格线(蓝图 §4.3-5,不是加分项) ### ① 实验矩阵四要素齐全(不是宏观叙述,是可执行矩阵) 每行一个可跑实验,**假设→变量→指标→停止条件**齐全(EXP-Bench 2505.24785:"设计"与"结论"最易跑偏)。`plan_lint` 把缺假设/缺停止条件/判定与指标脱节从盲区变逐行提示。停止条件**必可量化**(借 AI-Scientist v2 每阶段显式停止条件:收敛+≥2 数据集 / 预算耗尽),纯定性"效果好"不可验收 → warn。 ### ② 对照公平 + 消融隔离 + 统计显著(critical + warn) - **对照公平(critical)**:baseline 等量调参预算、同数据同划分、取最强可得(Dacrema 2019)。放水 = 提升假象 = critical。 - **消融隔离(warn)**:逐个移除创新组件证明贡献来源,因果声明配负对照排除替代解释。一锅端 = 归因不干净。 - **统计功效(warn)**:按 design 的独立单位做 power/sensitivity、报误差棒/CI、多重比较校正；多 seed 用来估算法随机性， 不能自动补患者/cluster 的样本量。单跑运气数不算证据。 ### ③ 能证伪(设计要让假设能被推翻) 每条假设有**反证条件**(什么结果能推翻它)。没有可证伪的实验 = 不是科学,是包装(Popper)→ critical。**可证伪 ≠ 已证伪**。 ### ④ 可复现全留痕(种子/环境/版本/划分) NeurIPS checklist:code+环境版本+权重+超参+多种子误差棒。**v2 强调最常漏的种子**:`PYTHONHASHSEED`(进程启动前)、 cuDNN `deterministic=True`+`benchmark=False`、DataLoader worker 种子。固定种子(可复现)≠ 多种子(重复实验),两者都要别混。 ### ⑤ 院士会追问(预演) 你的实验**能证伪你的假设吗**?对照**公平吗**(baseline 调够了吗)?消融能**干净隔离**每个组件贡献吗?效应的 CI/precision 支撑 claim 吗，power/sensitivity 的独立单位与 design 对齐吗?换个种子还成立吗?——答不上来的,方案没到及格线。 --- ## 收尾 self-check(出 verdict 前 / 回写总控前过一遍) - [ ] 实验矩阵每行**四要素齐全**(假设/变量/指标/停止条件)吗?停止条件**可量化**吗?(`plan_lint` 跑过、缺项清零) - [ ] question→population/单位→estimand→outcome/analysis 对齐吗?统计单位、随机化单位、分析单位没有偷换吧? - [ ] primary endpoint 的 measurement instrument、operational definition、unit、minimally meaningful effect 和 missingness policy 是否锁定? - [ ] analysis family 是否写明 independence assumption? 如果统计/随机化/分析单位不一致，是否有合理 rationale? - [ ] 每个 baseline 声明了**公平性条件**(等量调参/同数据/最强可得)吗?有放水的吗?(`fair_baseline` 非 unfair) - [ ] 每条假设有**可量化反证条件**吗?有推不翻的假设吗?(`falsifiable` 非 critical) - [ ] 每条假设是否写清 `success/failure/inconclusive` 三分支、动作与 claim impact? guardrail/kill criterion 是否有阈值与触发动作?(`failure_tree_gate`) - [ ] 每条强创新 claim 是否从 `innovation_engine` 的 anti_collage 追到可区分新机制 vs 旧解释的判别实验？若不能，是否降级为工程增量/系统化？ - [ ] 每条创新假设有**消融**隔离贡献吗?因果声明配**负对照**了吗?(`ablation_isolation`) - [ ] SESOI/效应量有来源与范围吗?功效方法匹配 design 吗?没把 seed/fold/同对象重复当独立 n 吧?复杂设计有 simulation/MDE 吗? - [ ] primary/secondary/exploratory、comparison family、exclusion、stopping/guardrail 锁了吗?预注册版本/hash/status 诚实吗? - [ ] 可复现清单的**种子全覆盖**(cuDNN/PYTHONHASHSEED/worker)吗?环境/版本/划分记账了吗? - [ ] 派生评测集规格写对(只动特征不碰标签/固定种子/仅评测)、回 data-engineering 构建了吗? - [ ] `research_package_gate.py --manifest plan_package.json --final` 跑过了吗?若 verdict=WARN，`warning_decisions` 是否写清修复/降 claim/用户授权?若 FAIL，是否还在 stage 5 修方案而不是交下游? - [ ] 没把启发式 lint **吹成"证明了对照绝对公平/假设绝对可证伪"**吧?(诚实标边界,终判需人) - [ ] 是回炉来的(7→5/13→5)?带着"哪条假设没撑住/审稿人质疑"**重规划**、**停下问用户**了吗? --- ## 名实对齐(诚实,不吹成卖点) **真增量(v2 兑现,已 selftest)**:① **对照公平/可证伪 critical 门 producer**(`plan_gate.py`,**v2 净新增接线**)—— 编排港来的 `plan_lint`(实验矩阵 linter)+ `power_check`(统计功效)+ 方案显式声明 → 产 `light.findings.v1`(producer= research-plan):**对照放水 / 假设无反证条件 → critical**(对齐 `STAGE_GATES[5]=[fair_baseline,falsifiable]`),消融不隔离 / 欠功效 → warn,被 `run_checkpoint --stage 5` 聚合 exit 1。v1 的 `plan_lint`/`power_check` **是纯 linter/工具、零产 `light.findings.v1`**(grep 实证),findings 接线是 v2 新增。② **将 `plan_lint` 的硬编码 `parents[2]/_shared` 改为规范 bootstrap** (v2 仓库根上移一层后必断)。③ **可复现清单补最常漏的种子**(cuDNN deterministic/PYTHONHASHSEED/worker 种子,v1 漏)。 ④ **实验矩阵模板加对照公平性声明 + 反证条件 + 负对照列**(对接 plan_gate 三 critical/warn 门)。⑤ Round 2 补 **question/estimand→design→power/sensitivity→预注册 provenance→checkpoint→下游/7→5** 八步资源闭环与注册模板； ⑥ 补 `target_chain.py`，把冻结目标链、计划哈希、用户授权、数据后 exploratory 降级、无环检查、风险账和比较公平字段 变成可执行门；Round 3 再补统计/随机化/分析单位、endpoint 测量操作化、最小有意义效应、缺失策略与独立性假设， 阻断“方案词很美但 endpoint 不可测 / seed 当独立 n / cluster 偷换单位”的常见翻车点；不扩大总控 critical 面。⑦ 补 `research_package_gate.py`，把“方案文本 + 矩阵 + target-chain 报告 + plan_findings + 预注册 + 复现清单 + warning 决策 + 用户授权” 变成 final 交付门；`PASS/WARN` 才能交 experiment-coding，`WARN` 必须有降 claim/后续处理和用户授权，`FAIL` 不得下游。 ⑧ Round 3 补 `failure_tree_gate.py`：把 success/failure/inconclusive 分支、guardrail/counter-metric、kill criterion、 资源耗尽默认动作和数据后 amendment policy 变成机读门，并接入 `research_package_gate`；没有失败树或 failure-tree report 非 PASS/WARN 的 final 包不得交下游，`WARN` 必须写 warning_decisions。 **裸模型本就会的(不吹)**:"baseline 要公平""要做消融""要多跑几个种子""假设要可证伪"——裸 Opus 都会说。本技能价值 = ① **把对照公平/可证伪落成确定性 critical 机读门 + 确定性阻断**(裸模型嘴上说公平、手上还是放过放水方案,编排器读不了); ② **功效/敏感性前置 + 多重比较联动**，并显式拒绝把 seed/fold 当独立 n；③ **机读 findings + 根因回炉** (research-plan 是 7→5/13→5 回炉落点,裸模型无此编排闭环)。 **诚实落后项(已知没做到)**: 1. **plan_lint 是启发式 linter、有边界**:查四要素齐全 / 判定可量化 / 判定-指标语义对齐(离线 semantic_sim 跨语言弱)/ 消融覆盖 / 负对照 / 多重比较族计数——**绝不"证明了对照绝对公平 / 假设绝对可证伪"**;严谨性评分是计数扣分制,**非真值、 非 ARA 语义认知评审**。公平/可证伪终判仍需人/领域判断。 2. **fair_baseline 靠声明 + 信号,不替你判 baseline 调够没**:门读方案**显式声明的公平性条件**;"等量调参预算是否真等量" 须人核;未声明 → warn 提示补,**不编造"放水"**(GIGO)。 3. **falsifiable 查"有没有反证条件",不查"反证条件对不对"**:反证条件设得合不合理、能不能真达到须领域判断。**可证伪 ≠ 已证伪**。 4. **功效覆盖窄且对假设极敏感**:`power_check` 只适用双独立样本均值近似；d 来源须 SESOI/外部证据/经收缩 pilot。 paired/ANOVA/比例/相关/cluster/mixed/repeated-CV 用对应 Power 类或 simulation；固定 N 报 MDE/sensitivity。statsmodels 缺失降级正态近似标 [APPROX]。机器不会验证效应来源真伪。 5. **与 data-engineering 功效分工(不重叠)**:data-engineering `sample_size_check` = 提 idea 前数据规模**经验粗筛**(每类 最小样本/EPV,无效应量,门 idea 2⊣3)；research-plan 在明确 estimand/design 后做正式 power 或 sensitivity。 `power_check` 只是其中双样本 t 子集，不代表所有方案都已正式 power。 6. **不重造实验追踪/版本/扫参轮子**:DVC/MLflow/W&B/Hydra/Sacred 是成熟工具,本技能**教选型 + 给真实命令**(references), 不内置追踪服务器/数据版本库;分档选型(轻/标/完整),别给小课题套重型(Snakemake Windows 兼容差→WSL/invoke/make)。 > 标准产出工件:`PROJECT_PLAN.md`(研究方案,交 experiment-coding)· `experiments/experiment_matrix.md`(实验矩阵)· > `preregistration.md`(冻结计划+registry provenance)· `reproducibility-checklist.md`(复现清单)· > `plan_findings.json`(对照公平/可证伪门)· `target-chain.json`(冻结目标链+授权/变更账)· > `failure-tree.json` + `failure_tree_report.json`(成功/失败/无结论/guardrail/kill criterion)· `derive_spec`(派生评测集回 > data-engineering)· `plan_package.json` + `research_package_report.json`(final 交付门证据)。落 `.light/`,passport 登记交 > memory-pm,方案变更回写 `.light/decision_log`。 --- ## 参考(三级渐进披露:需要时再读) - 对标真相源:[`docs/competitors/research-plan.md`](../../docs/competitors/research-plan.md)(10 真同类 skill / 7 repo + OSF·AsPredicted·SPIRIT/CONSORT·ICH E9(R1) 等机制锚 + 诚实差距) - 真实研究者资源闭环:[`references/research-plan-resource-map.md`](references/research-plan-resource-map.md)(question/estimand→design→power/sensitivity→outcome lock→baseline/ablation→registry freeze→stage-5 checkpoint→experiment-coding/7→5；access 分级) - 工具一手核查笔记(真实端点/命令/已知坑):[`references.md`](references.md)(DVC/MLflow/W&B/Hydra/Snakemake/sklearn/PyMC/statsmodels/功效/预注册/算力预算/复现协议) - 引擎脚本:[`scripts/`](scripts/)——各 `--selftest`/`--help` 即接口;`plan_gate.py`(对照公平/可证伪 critical 门)是 findings 核心，`target_chain.py` 是冻结链门，`failure_tree_gate.py` 是失败树/guardrail 门，`research_package_gate.py` 是 final 计划包交付门 - 模板:[`templates/research-plan.md`](templates/research-plan.md)(方案)· [`templates/target-chain.example.json`](templates/target-chain.example.json)(故意不完整的目标链安全起点)· [`templates/failure-tree.example.json`](templates/failure-tree.example.json)(故意不完整的失败树安全起点)· [`templates/experiment_matrix.md`](templates/experiment_matrix.md)(四要素矩阵+单位/family+对照公平+反证条件+派生规格)· [`templates/preregistration.md`](templates/preregistration.md)(outcome/exclusion/stopping/version/hash)· [`templates/reproducibility-checklist.md`](templates/reproducibility-checklist.md)(种子全覆盖)· [`templates/plan_package.manifest.example.json`](templates/plan_package.manifest.example.json)(final 交付 manifest)· [`templates/reproduction-log.md`](templates/reproduction-log.md)(复现日志) - 案例:[`examples/plan_spec.example.json`](examples/plan_spec.example.json)(plan_gate 干净方案 spec → verdict=pass) - 地基契约:[`_shared/README.md`](../../_shared/README.md)(`findings_schema` · `gate_runner` · 规范 bootstrap) - 上游/下游:[`light-idea-critique`](../light-idea-critique/)(stage 4,放行 idea)· [`light-data-engineering`](../light-data-engineering/)(stage 2,数据卡 + `derive_eval_set.py` 派生评测集回边)· [`run_checkpoint.py`](../light-orchestrator/scripts/run_checkpoint.py)(stage 5 聚合 exit 1)· [`reroute.py`](../light-orchestrator/scripts/reroute.py)(ROUTES[7→5]/[13→5] 回炉落点)· experiment-coding(stage 6,按矩阵实现)· result-analysis(stage 7,7→5 回边)