power-analysis

功效分析循环

用于两组比较的功效分析与预注册循环。产物是研究的统计计划；反馈信号有两个部分——统计功效（通过对计划采用的检验进行蒙特卡洛模拟来估算）和效度缺陷数量。每次迭代都会模拟功效、求出达到目标所需的样本量、检查设计是否存在缺陷并进行修订，直到功效达到目标且缺陷清单为空。最终交付物是一份样本量论证，以及一份在查看任何数据之前就确定假设、主要结果、分析方法、样本量和停止规则的预注册。

范围与局限

此循环仅循环执行三项工作：（1） 通过模拟计算两组比较的功效和所需样本量，（2） 按照固定的效度检查清单检查设计，以及**（3）** 撰写一份预注册。随附的功效模型（tools/power_sim.py）仅涵盖双样本均值（连续结果）和双比例（二元结果）检验。

它不是通用实验设计工具。它不处理析因、重复测量、集群／多层、时间序列、自适应或生存设计；不会根据领域知识为你选择结果指标或操纵变量；也不会分析你已收集的数据。对于这些情况，这里的功效数值并不适用——请使用适合相应设计的功效方法。如果研究不是简单的两组比较，请说明并停止，不要报告与计划分析不匹配的功效。

适用场景

当主要结果是连续均值或二元比例时，可使用此工具为一次两组比较确定样本量并进行预注册。默认以用户提出的最小关注效应为基准计算功效；如果用户不确定该效应，应帮助他们根据基线和最小有意义差异来确定，而不是乐观猜测——按照大于现实效应的效应量来设计所谓“有功效”的研究，只是虚构。如果研究不是两组比较，请停止并指出适合该设计的方法。

设置

以交互方式解析绑定项。如果工作目录中存在 loop.run.yaml，则加载该文件，用一行确认其中的值，然后直接进入循环。否则：在 Claude Code 中（可使用 AskUserQuestion 工具），为每个绑定项推断一个可能的值，并将其作为推荐选项呈现；在其他主机上，则针对每项使用带引号的纯文本提示进行询问。然后写入 loop.run.yaml（格式：examples/run.example.yaml），并在创建任何其他文件之前确认各项的值。

绑定项	含义	默认值	推断方式
<hypothesis>	实验所检验的主张	—	询问用户
<outcome>	主要结果类型 + 最小关注效应：连续型（baseline_mean、sd、min_effect）或二元型（baseline_rate、min_lift）	—	询问用户；该项决定计算功效时采用的效应量
<target_power>	设计必须达到的功效	0.80	—
<alpha>	显著性水平	0.05	—
<power_cmd>	调用随附模拟器的命令	python3 <skill_dir>/tools/power_sim.py --design <two-sample-mean|two-proportion> --effect <e> [--sd <sd> | --baseline <p0>] --alpha <alpha> --n <n_per_group>	—
<design_doc>	设计文档 + 预注册文件的输出路径	<sandbox_root>/design.md	—
<sandbox_root>	设计文档和日志的存放位置	./sandbox	—
<budget>	最大迭代次数	8	—

<power_cmd> 会输出一个 JSON 对象：{"power", "n_per_group", ...}。请运行该命令以获取功效；切勿手动估算功效。

循环

复制此清单并逐项勾选：

• 第 0 轮迭代——将设计草案写入 <design_doc>；暂不记录任何最终结论。
• 模拟功效：在当前 n 和假定效应下运行 <power_cmd>。
• 求解 N：如果功效 < <target_power>，则用更大的 n 重新运行（先逐步增大，再二分搜索），直到达到目标。
• 审查有效性：列出下方清单中发现的每一项缺陷。
• 修订：修复优先级最高的缺陷，将 n 设为满足功效要求的值，并更新 <design_doc>（以及预注册部分）。
• 追加一行记录；当功效达到目标且没有剩余缺陷时停止，否则在达到 <budget> 时停止。

第 0 轮迭代——草案。 在 <design_doc> 中写下初步设计：各组/条件、分析单位及单位分配方式、主要结局和精确计划检验、假定效应量（来自 <outcome>），以及初步样本量估计。暂不记录任何最终结论。

然后，持续迭代，直到满足停止条件（达到功效且没有缺陷，或达到预算）：

1. 模拟功效。 在当前每组 n 和假定效应下运行 <power_cmd>，并使用与计划检验相匹配的 --design。记录达到的功效。
2. 求解 N。 如果 power < <target_power>，则用更大的 n 重新运行模拟——逐步增大（例如翻倍），然后二分搜索——直到功效达到目标，并采用该 n。
3. 审查有效性。 根据清单检查设计，并列出发现的每一项缺陷：
   • 混杂 / 无对照——是否有同期对照组？还是拿存在其他差异的历史/其他来源基线进行比较？
   • 随机化——单位是否随机分配？如果没有，选择偏差可能影响任何效应估计。
   • 选择 / 抽样——样本是否能代表所声称结论所针对的总体？
   • 多重比较——是否检验了多个结局/亚组，却未进行校正？
   • 可选停止 / 偷看数据——是否预先规定了停止规则？还是会反复分析，直到结果显著？
   • 结局与分析的预先设定——主要结局和唯一的计划检验是否事先确定（而非看过数据后再选择）？
   • 测量——结局是否测量可靠，并在可能的情况下对条件保持盲态？
4. 修订。 修复优先级最高的缺陷（或一对无法单独修复且紧密关联的缺陷，例如增加同期对照并随机分配单位），并将 n 设为满足功效要求的值。更新 <design_doc>，包括预注册部分：假设、主要结局、唯一计划分析、样本量及其推导方式、随机化方案和停止规则。
5. 记录一行记录并继续。

当 power ≥ <target_power> 且缺陷列表为空时，或达到 <budget> 时，停止。报告最终设计与预注册内容、达到的功效和所需 n；如果因预算而停止，还要报告仍未解决的缺陷。

记录表

<sandbox_root>/ledger.tsv，使用制表符分隔，文本中不得出现逗号。表头：

iter	n_per_group	power	open_flaws	change

示例：

iter	n_per_group	power	open_flaws	change
0	50	0.50	2	draft: volunteers vs last-year cohort, n=50
1	100	0.80	1	solved n for 80% power at d=0.4
2	100	0.80	0	randomized concurrent control; pre-specified single primary outcome + stopping rule

报告最佳迭代：最终设计、达到的功效和所需 n，以及因预算而停止时仍未解决的任何缺陷。

约束

• 功效按最小关注效应计算，而非乐观估计值，因为按大于现实的效应计算功效的设计检测不到真实效应——且模拟中的 --design 必须与设计中指定的检验一致。不要编辑 tools/power_sim.py。
• 设计不能仅凭功效过关——功效充足但存在混杂或未随机化的设计仍不合格；两道关卡（功效和缺陷）都必须通过。
• 先预注册，再收集数据，这样最终检验才是验证性检验，而不是看到结果后才选定的检验：分析方法、结果指标、样本量和停止规则都要提前确定。
• 一个主要结果指标和一项计划检验决定功效和结论；次要分析应标记为探索性分析。
• 沙盒是自包含的——不得通过 ../ 越界。不要暂停循环询问是否继续。