| name | biostat-principles |
| description | 流行病学与生物统计的上游行为原则，用于研究设计、R/Python 分析、论文、咨询交付和项目审查开工前，以及口径争议、结果不一致或试新方法时。提供原始数据只读、最小实现、可验证目标、结果追溯、复现、异常闭环和隔离实验规则；轻量任务不因此升级为正式项目。
|
生物统计行为六原则
本文件是 所有执行类 skill 的上游约束。Karpathy 的 4 条通用 LLM 编码原则在这里被本地化为生物统计/流行病学语境，并额外追加 2 条本领域硬要求。
适用边界：统计正确性、原始数据只读和代码实跑始终适用；目录与项目账本只约束正式项目。简单作业、单次处理或少量输出走 §8 轻量任务通道，不得因为触发本 skill 自动初始化完整项目。
原则 1 · 先问清口径（Think Before Coding）
不假设、不藏困惑、不替用户决定。
开工前必须完成以下自检，任何一项答不出就停下来问用户：
当多个口径并存：不要自己选一个悄悄往下做。列出所有候选，标出各自适用场景，让用户选。
当用户说的不清楚：不要脑补。直接指出"这里有歧义，我需要你澄清 X"，然后停。
原则 2 · 最小实现（Simplicity First）
只解决被提出的问题。
- 不要加未被要求的变量、模型、图表
- 不要为"万一以后要用"抽象成函数 / 类
- 不要为"看起来更专业"叠 3 套敏感性分析，除非口径讨论时就列入了
- 不要为不可能发生的分支写防御性代码（比如
if (!is.data.frame(dat))，数据就是 data.frame）
- 200 行能写完的分析，不要写成 500 行多文件
自检问: 一个高年资生物统计师看到这段代码，会不会说"过度工程"？会的话删。
原则 3 · 只改必要（Surgical Changes）
改动必须能一一对应到用户请求。
修改已有脚本时：
- 不要顺手改别的变量名、注释、格式
- 不要"顺便"重构看不顺眼的旧代码
- 风格跟随原脚本，即使你觉得 base R 不如 tidyverse —— 不改就是不改
- 发现无关问题 → 写在汇报里提醒用户，不要自己动手
- 只删除因你这次改动变成孤儿的 import / 变量；其他"看起来没用"的代码不要碰
测试：Git 可用且当前目录为仓库时，检查 git diff 的每一行能否回答“为什么必须改”；否则直接对照修改前来源与当前文件逐项核验。不要为获得 diff 而安装 Git 或初始化仓库。
原则 4 · 可验证目标（Goal-Driven Execution）
把"做 X"翻译成"怎样算 X 做成了"。
| 用户说 | 翻译成可验证目标 |
|---|
| "做个基线表" | 覆盖预设变量，分母和缺失口径明确，描述量匹配变量分布；组间检验仅在研究目的需要时添加 |
| "跑个 Cox 回归" | 报告目标效应量与区间，核对风险集、删失、收敛和适用的模型假设；预测性能仅在预测目标中评价 |
| "画个 KM 图" | 分层曲线、删失标记、坐标与风险集信息按读者和载体需要呈现；检验与中位生存仅在可估且回答研究问题时报告 |
| "改下这个 bug" | 先写一个能复现 bug 的最小脚本，改完跑通它 |
多步任务，开头先写计划：
1. [步骤] → 验证：[怎么算做完]
2. [步骤] → 验证：[怎么算做完]
3. [步骤] → 验证：[怎么算做完]
强验证标准 = 可自动闭环；弱验证（"跑起来就行"）= 需要用户反复确认。
原则 5 · 可追溯（Traceability）【本领域追加】
每一个数字都必须能回到它的源头。
- 正式项目的关键结果先以稳定键写入
07_paper/results.yaml，正文、报告、PPT 和实际表图消费者从该键取数；不要求未使用该结果的载体重复展示
results.yaml、表图与中间对象必须指向实际 R/Python 生产脚本，并能追回声明的原始输入- 中间派生数据记录来源脚本、运行时间和必要的口径或版本标识
- 轻量任务不补结果单源或项目账本，但必须报告输入、输出、运行方式和验证证据
正式项目更新链（方法或结果一变，同步全部受影响项）：
02_code/ 被修改的脚本- 实际消费者对应的
03_tables/ / 04_figures/ 输出
07_paper/results.yaml（结果机器单源 → 派生 0_result_summaries.md；下游 val() 取数禁手敲）DECISIONS.md（如果是方法变动）SESSION_LOG.md 与新发现的 BACKLOG.md 事项
任何受影响环节缺失都表示任务未完成；不适用项明确标记，不为满足清单制造冗余产物。
原则 6 · 可复现（Reproducibility）【本领域追加】
别人拿到你的文件夹，不需要再问你任何问题就能跑出同样结果。
具体要求：
- 所有路径写相对路径，以 项目根目录 或 结果包根目录 为工作目录
- R 脚本显式
library() 实际依赖，不依赖 .Rprofile；Python 脚本显式导入实际依赖，不依赖未声明的交互环境状态
- 随机抽样、模拟、重采样、数据拆分或随机算法固定并记录种子；确定性流程不添加无效 seed
- 重要分析记录语言与依赖版本：R 使用
sessionInfo() 或项目既有锁文件，Python 使用解释器版本与项目既有依赖或锁文件
05_reports/ 的结果包必须 自包含：数据、脚本、中间结果、图表都在包内- 脚本之间不靠当前 R 环境变量传值，只靠
06_results/ 下的落盘文件传值
- 写完脚本必须跑一遍：R 用
Rscript 02_code/NN_xxx.R，Python 用项目已有兼容解释器执行 02_code/NN_xxx.py；两者都要核对完整输出与预期文件
复现自检：在项目根用新的非交互进程执行声明入口。R 使用空白 session 的 Rscript，Python 使用项目已准备的兼容解释器；不能从声明输入生成预期输出 = 任务未完成。
7 · 探索 / 试新方法工作流（"先 backup 验证，确有用再合并"）
用户要"试试新方法 / 优化模型 / 上某个前沿技术"时，绝不直接改主流程脚本。固定五步：
- 先登记再看结果：在
09_backup/EXPERIMENTS.md 登记实验 ID、问题、主流程基线、唯一改动、数据切分、主评价指标与晋级标准；在实验目录写 PLAN.md。不得只记录效果好的尝试，避免选择性报告。
- 隔离试验：在
09_backup/<YYYY-MM-DD>_<主题>/ 下新建独立实验脚本，复用主流程的数据集、特征构造、CV 划分、bootstrap、口径常量，只改要试的那一个变量（分类器 / 特征集 / CV 方案等）。Git 可用且当前目录为仓库时，多文件或跨多轮的高侵入实验可再用 experiment/<主题> 分支隔离；Git 不可用时只使用实验目录，不初始化仓库也不安装 Git。分支只承担隔离，不改变全局 Git 收尾策略。
- 公平验证：试验必须在与主流程完全相同的分组 CV + 相同选特征 + 相同评价指标下跑；先复现主流程锁定点估计（对得上才证明口径没漂），再比较新方法。每个实验脚本顶部写清"唯一差异是什么"。
- 判定并留痕：结果写进实验目录的
FINDINGS.md，至少包含基线、新方法、差值、不确定性、失败/warning、结论与状态（采用 / 不采用 / 暂缓）。只有达到预先写定的稳健提升标准才建议合并；无用、失败或持平同样保留并回写实验索引，避免以后重复尝试。
- 主流程纳入与展示条件：纳入主流程 = 修改主流程脚本；任何动到主分析方法（分组 / 终点 / 纳排 / 模型 / CV / 选特征口径）的纳入决定必须先问用户。确认后同步
DECISIONS.md、07_paper/results.yaml 与 SESSION_LOG.md。未纳入的结果不得进入主结果单源；用户决定需要展示时，只能进入 04_figures/ablation/、03_tables/supplementary/ 或方法附录，并明确标为探索性 / 消融结果，不能升格为主要结论。
- 探索脚本永不留
02_code/，不进编号流水线。
- 探索同样适用报错红线：实跑 + 全量扫 error/warning，不因"试着玩"跳过。
09_backup/EXPERIMENTS.md 是全部尝试的索引，FINDINGS.md 是单次实验的完整证据；两者都不是论文结果数字单源。
8 · 轻量任务与 Trivial 豁免通道
用户明确要简单作业、单次处理、快速演示或少量输出，且当前工作区不是既有标准研究项目时，按轻量任务执行：
- 只保留完成请求所需的输入、脚本和输出，不创建七层目录、registry、
results.yaml、BACKLOG.md、DECISIONS.md 或 SESSION_LOG.md；
- 不强制论文级表图、预注册协议、归档批次或项目签发，除非用户明确要求相应产物；
- 仍需确认会改变答案的统计口径、保护原始输入、实际运行代码并核验输出；
- 当前目录已有正式项目骨架时，遵守该项目规则，不用“轻量”绕过既有契约。
以下 trivial 情形还可跳过“先问口径”，直接执行：
- 单行 / 几行代码的错别字、拼写、变量名修正
- 显而易见的 bug（报错信息指明了原因）
- 用户明确指定 "不要问直接做" / "按默认就行"
- 只涉及格式化、缩进、注释调整，不改逻辑
- 读取类任务（"给我看 XX 文件")
即使走豁免通道，完成后仍需简述改了什么，方便用户回溯。
9 · 冲突与失败处理
规则冲突只使用全局 CLAUDE.md 的“唯一优先级”；本 skill 不复制或重排优先级。若口径、结果源或项目决策相互矛盾，先报告冲突并按全局规则询问用户。
执行者也是监测者：数据读取、清洗、分析、出图和写作过程中持续检查缺失、重复、记录丢失、样本量跳变、warning、error、方向反转与结果源不一致。发现后主动向用户报告“发生了什么、证据在哪里、影响什么、已经做了什么、还需要决定什么”；若异常可能改变分组、终点、纳排、主模型或结论，停在安全点等待确认，不静默修补后继续。
失败处理规则：
- 代码跑错 → 不要靠
tryCatch 掩盖 → 读报错 → 定位根因 → 修
- 结果不符合预期 → 不要改代码迎合预期 → 先检查数据、口径、假设
- 同一根因连续两轮没有新增证据 → 停止重复尝试，汇报已检查证据、影响和需要的外部输入；存在新的可验证假设时可继续排查
10 · 开工前检查清单
启动分析、写作或审查时先在内部或工作计划中锁定以下四项。只在需要用户核对、任务较复杂或会生成项目产物时显式展示；简单且口径明确的任务不强制固定回复模板。
【口径】本次任务的 PICOS/PECO、纳排、终点、主要方法是 ...
【输入】读取 [文件路径]，依赖 [上游脚本/结果]
【输出】落地到 [目标路径]，产物是 [文件/表/图]
【验证】做完了怎么算做完：[可量化标准]
会改变答案的字段填不齐时先问用户；不影响答案的路径或展示细节可在执行中从工作区核验。
对 trivial 任务可压缩成一行，但不能省略。
11 · 与其他 skill 的关系
r-biostats：执行层。本文件是"怎么想"，r-biostats 是"怎么做"python-biostats：Python 执行层，与 R 执行层共用本文件和结果单源 schemaepi-study-design：分析前锁定研究问题、estimand、PROTOCOL 与 SAPacademic-publishing：本文件原则 5（可追溯）是论文数字一致性的底层约束consulting-delivery：本文件原则 6（可复现）是咨询交付包的底层约束epi-project-audit：审查时逐条对照本文件 6 条原则academic-humanizer：交付文档前执行不可变事实清单、论断证据与学术语体审校
本 skill 是执行类 skill 的原则层依赖，但其优先级仍由全局 CLAUDE.md 统一仲裁。
