epi-project-audit

name	epi-project-audit
description	六层审查流行病学与生物统计项目的数据链、代码、结果、表图、正文和交付一致性，并以证据判定是否可签发。用于项目质控、结果复核、审稿前自查或全面一致性检查；只审查时不修改文件。上游为 biostat-principles，含咨询包时同时核对 consulting-delivery。

Epi Project Audit（6 层审查）

审查本质：证据链核对。不只看代码、不只看结果；看的是"数据 → 代码 → 结果 → 表图 → 正文"这条链是否首尾一致。 工作模式：六层按顺序逐项过 TODO；某层失败时记录证据、按权限修复或给出建议，并继续完成其余层审查。任何未闭环的 fail 都阻止签发，只有全过才发 pass。 结构单源：目录、命名、registry、归档与 BACKLOG 的规范以 ../project-init/references/project-hygiene.md 为准。

---

一、开工前准备

1.1 读项目规则（顺序优先）

按以下顺序读取，先服从项目级规则，再执行本 skill：

1. 项目内 CLAUDE.md / AGENTS.md
2. README.md（项目说明）
3. PROTOCOL.md / SAP.md（预设研究问题、分析与偏离边界）
4. DECISIONS.md（方法决策与方案偏离历史）
5. SESSION_LOG.md（操作日志）
6. 07_paper/results.yaml（结果机器单源）+ 派生 0_result_summaries.md

缺失关键文件就已经是扣分项，要写入"Problems found"。

1.1bis 确定性预检（强制）

在进入六层人工审查前运行：

python <本技能目录>/scripts/run_check_project.py <项目根> --json

run_check_project.py 从 ~/.codex/.epiagentkit-install.json 或 ~/.claude/.epiagentkit-install.json 的 source 键解析中央 EpiAgentKit 仓库，再调用其中的 scripts/epiagentkit.py check-project。不得只在当前研究项目或 PATH 中查找 epiagentkit.py，也不得在未检查安装清单前报告“当前机器未找到”。可先用 --print-cli 核验解析结果。

把 findings 映射到对应 Layer。任何 ERROR 都阻止最终签发；WARN 必须解释，但不得把无 provenance 时的 mtime 提示升级成确定性不一致。该命令只做预检，不替代代码实跑、数字矩阵或科学判断，不注册为 Stop hook。

1.2 确定范围

用户未限制范围时直接执行六层全量审查，不为默认选择暂停。用户明确指定代码、结果、论文、交付物或某个路径时只审该范围，并在 verdict 中写明未覆盖层。

---

二、6 层审查流程（每层有明确判定标准）

[START]
  ↓
[Layer 1: 项目骨架]      ——判定标准：目录结构、命名、日志完整
  ↓ 不过 → 记录问题 + 按权限修复/建议 + 继续收集其余层证据
[Layer 2: 数据链]         ——判定标准：原始只读、派生可追溯、缺失有交代
  ↓
[Layer 3: 代码质量]       ——判定标准：可运行、无 error、脚本编号
  ↓
[Layer 4: 结果一致性]    ——判定标准：表图/摘要/正文数字完全一致
  ↓
[Layer 5: 科学合理性]    ——判定标准：方法适配、结论不超证据
  ↓
[Layer 6: 交付一致性]    ——判定标准：README/日志/决策/分享包同步
  ↓
[VERDICT]  pass / pass with concerns / fail

每层的判定：

• 绿（pass）：全部 TODO 通过
• 黄（concerns）：有非阻塞问题，已写入报告
• 红（fail）：有证据链断裂、数字不一致、结论无支撑 → 必须修复后重审，不可签发

---

三、Layer 1 · 项目骨架审查

TODO 清单

• 目录结构符合七层规范（01_data / 02_code / 03_tables / 04_figures / 05_reports / 06_results / 07_paper / 09_backup）
• 01_data/rawdata/ 及额外声明的 raw roots 存在，check-project 未发现 Git 工作区修改；非 Git 数据另核来源与只读证据
• 02_code/ 内阶段脚本按 NN_描述.R|py 编号且连续无断号；无来源不明的 test.*、final.*、temp.*
• 02_code/ 编号脚本数 ≤ 10（config / conventions / lib / run_pipeline 与 vendored/ 不计）；探索 / 一次性脚本不在 02_code/（应在 09_backup/）
• 03_tables/ / 04_figures/ 编号按论文行文顺序连续无断号；TableS{N} / FigS{N} 在 supplementary/；无 Table_xxx / Fig_xxx 无编号残留；交付 xlsx 内无 cover / 说明类解说性 sheet
• 根目录无散落临时文件（.csv、.xlsx、.png 不在根）
• CLAUDE.md / PROTOCOL.md / SAP.md / SESSION_LOG.md / DECISIONS.md 存在；入口规则文件不超过 200 行
• 09_backup/EXPERIMENTS.md 登记全部探索尝试；每个已运行实验有 PLAN.md 与 FINDINGS.md
• 09_backup/ 存在；旧版文件已归档，不在活跃目录
• 没有多个互相冲突的"最终版"（比如 final/ + 最终版/ + 提交版/）

红线（任一触发 → Layer 1 判 fail）

• 根目录存在 > 3 个散落非规范文件
• 02_code/ 存在无编号脚本
• 原始数据有 Git 修改、来源哈希变化或其他可核验证据；不得只凭 mtime 判定
• 09_backup/ 和活跃目录共存同名文件但内容不同

修复处理

按 §十一的审查/修复模式与权限边界执行。来源不明的 test.R、temp.R、根目录文件或多版本产物不得因命名看似不规范就自动移动、重命名或删除；先确认所有权、引用关系与当前版本。只有用户要求修复且目标位置唯一、引用可同步、验证可闭环时才处理。

---

四、Layer 2 · 数据链审查

TODO 清单

• 01_data/rawdata/ 下每个文件都有对应的数据字典（README 或单独 md）
• 原始数据只读（检查是否有脚本 write 回 01_data/rawdata/ → 违规）
• 派生数据全部在 06_results/ 或结果包 data/
• 每个派生数据能追溯到生成脚本（用 git grep / 搜索引用）
• 关键变量在字典里有定义、单位、来源说明
• 缺失数据有处理记录（删？插补？在哪个脚本？哪个决策）
• 样本量从原始 → 清洗 → 分析，每一步的损失数量可追溯（CONSORT / STROBE 流程）

红线

• 发现脚本修改了 01_data/rawdata/ 的文件
• 存在无法追溯来源的派生数据
• 样本量链断裂（原始 1000 → 分析 500，但中间去了谁没说）

---

五、Layer 3 · 代码质量审查

TODO 清单

• 真实跑一遍：用项目声明的 R 或 Python 入口执行完整主流程；成本过高时至少实跑主分析并说明未覆盖部分
• 无 error，warning 已理解且合理
• 依赖声明完整；只有随机流程需要固定并记录 seed
• 用相对路径（grep setwd、grep "C:/"、grep /Users/）
• 循环、向量化或批处理选择可读且无索引错误；无临时调试输出残留
• 中间格式与消费者和项目合同匹配，跨脚本依赖通过声明的落盘文件传递
• 正式项目无写死的 Table\d / Fig\d 输出路径；产出经对应语言的 registry helper 生成
• 结果包（05_reports/*/）内脚本不回读项目根（grep \.\./）

红线

• 任何 R 脚本报 error
• 01_data/rawdata/ 被脚本写入
• 绝对路径出现（移植性破坏）
• 结果包内脚本依赖包外文件

可修复项

仅在“审查并修复”模式且满足 §十一权限边界时处理；“只审查”模式只记录证据与建议：

• 临时调试输出残留 → 删除；有用的长期进度或审计信息保留为语义日志
• setwd() 绝对路径 → 改 here::i_am() 或 Rproj 提示
• 输出格式不符合既有消费者合同 → 回到生产脚本统一生成

---

六、Layer 4 · 结果一致性审查（最关键）

这是一切审查的核心：数字必须从"数据源 → 脚本产物 → 表 → 图 → 摘要 → 正文"一致到底。

先跑自动审计（结果单一真源项目）

若项目已用结果单一真源（07_paper/results.yaml，见 biostat-principles/references/result-summary-schema.md），先跑：

python <此skill>/scripts/check_consistency.py <项目根>

它双向比对交付文档（论文/报告/PPT）里的 CI、P 与 results.yaml：方向A 报"文中统计量在源中无匹配"（疑似手敲/陈旧/未回写），方向B 报"源有文档未用"，并列出 interp_review 的"解读待复核"键。退出码非 0 表示 Layer 4 未通过。脚本是初筛，下方人工矩阵仍需补图内/精度等它覆盖不到的项。

TODO 清单

• 从 07_paper/results.yaml 取出每一个关键数字（样本量、主效应、P 值、95%CI、事件数），并核对派生 0_result_summaries.md 完全一致
• 每个关键数字至少有可审计的生产者和实际消费者；未使用该数字的表、图或正文记为不适用，不要求重复展示
• 数字在其实际消费者之间一致，图形仅在设计需要时呈现风险表、脚注或数值标签
• 数字精度全文统一（不能一处 0.45，一处 0.4453）
• 亚组分析和主分析的样本量能对得上
• 敏感性分析与主分析的差异已解释；方向不一致是需要评估的证据，不自动判定失败

红线

• 正文某个数字在 07_paper/results.yaml 找不到 → fail
• 摘要的 HR 与结果表的 HR 不一致 → fail
• 图上的 N 和基线表的 N 不一致 → fail
• 讨论结论引用的数字在表里不存在 → fail

强制输出

Layer 4 审查必须输出一张数字一致性矩阵：

关键数字	results.yaml	0_result_summaries.md	03_tables/	04_figures/	07_paper/	一致？
样本量 N	1234	1234	Table1: 1234	不适用	摘要: 1234	一致
主 HR	1.45	1.45	Table3: 1.45	Fig2 forest: 1.45	摘要/讨论: 1.45	一致
P 值	0.004	0.004	Table3: 0.004	—	摘要: 0.004	一致

任何一行不一致 → Layer 4 fail。

---

七、Layer 5 · 科学合理性审查

TODO 清单

• 研究设计（队列/病例对照/横断面/RCT/Meta）明确
• 主终点、分析人群和主要模型与冻结的 PROTOCOL/SAP 一致；偏离均在 DECISIONS.md 有时间、原因和确认记录
• 主分析方法匹配 estimand、结局类型、时间结构、抽样和数据相关性；方法名称不能代替适用性论证
• 纳排标准前后一致（方法节说的排除标准，和 CONSORT 流程图一致）
• 样本量、有效事件数、参数复杂度、惩罚或收缩、验证方案和不确定性足以支持目标分析；不把单一经验阈值作为普遍红线
• 完成与模型和 estimand 相关的诊断，并说明不适用项
• 敏感性分析覆盖了主要的口径假设
• 探索实验完整登记而非只保留“最佳”结果；主线采用项达到预设晋级标准，未采用项未混入主 results.yaml
• 适用的 STROBE、CONSORT、PRISMA、TRIPOD 或其他报告规范已识别并核对

红线

• 方法学严重错配（比如 RCT 分析忽略了随机分层）
• 主要分析在看过结果后变更，却未记录为 SAP 偏离或探索性分析
• 只报告成功尝试、无法还原全部方法搜索过程，或未满足主流程纳入条件的探索结果被写成主要结论
• 有效样本或事件信息相对模型复杂度不足，却未采用限制复杂度、惩罚、内部验证或不确定性披露
• 缺关键假设检验却未说明

结论强度标定（核心）

扫描讨论和摘要，检查以下"过强措辞"：

原文	问题	改为
"证实" / "证明"	观察性研究无法"证实"	"支持" / "提示"
"明确说明"	过强	"方向一致"
"稳固的保护作用"	过强 + 情感词	"保护方向"
"可以得出结论"	过强	"结果提示"
"显著降低风险"	混淆统计显著和临床意义	"与较低风险相关"
"具有因果意义"	观察性证据不支持	"存在关联"

全文逐条列出超纲措辞的位置 + 建议替换。

---

八、Layer 6 · 交付一致性审查

TODO 清单

• README.md 与实际目录一致
• SESSION_LOG.md 的最后一条时间 ≥ 最近一次代码修改时间
• DECISIONS.md 覆盖所有方法选择（grep 方法名 vs DECISIONS.md）
• 05_reports/ 的分享包能独立运行（可随机抽一个实测）
• 分享包的 00_写作说明.md / 01_方法与结果.docx 与包内代码和表一致
• 分享包如果面向客户 → 过 consulting-delivery 的 FINAL 终检清单（§八）
• 旧版、废弃版本全部在 09_backup/

红线

• 分享包无法独立运行（依赖外部文件）
• docx 结论与包内 tables 数字不一致
• 未披露的敏感性分析或亚组分析在正文提及

---

九、如何使用 references/

• 完整逐项审查表 → references/audit-checklist.md
• 结论措辞标定表 → references/claim-calibration.md

两份文件是本 skill 的展开，逐项对照使用。

---

十、输出合约（OUTPUT CONTRACT）

审查结束后必须用以下结构输出：

## Audit verdict

- Status: pass / pass with concerns / fail
- Scope: [审查范围，哪些层]
- Date: YYYY-MM-DD
- Reviewer: [用户提供的姓名或角色；未提供则写“未记录”]

## Layer-by-layer results

| Layer | 内容 | 结果 | 主要问题 |
|-------|------|------|---------|
| 1. 项目骨架 | 目录/命名/日志 | pass / concern / fail | ... |
| 2. 数据链 | 原始只读/派生可追溯 | pass / concern / fail | ... |
| 3. 代码质量 | 可运行/规范/路径 | pass / concern / fail | ... |
| 4. 结果一致性 | 数字全链一致 | pass / concern / fail | ... |
| 5. 科学合理性 | 方法/结论标定 | pass / concern / fail | ... |
| 6. 交付一致性 | 日志/决策/分享包 | pass / concern / fail | ... |

## Numbers consistency matrix

[Layer 4 产出的表格完整粘贴]

## What is correct

- [已验证正确的点，说服力最强的结论]

## Problems found（按严重度排序）

### Critical（必须修复）
- [证据链断裂、数字不一致等 fail 级问题]

### Warning（建议修复）
- [命名不规范、注释不足等 concerns]

### Fixed in this audit
- [本次审查直接客观修复的小问题]

> 审查中发现"非阻塞但该补"的项（缺某项数据、某分析能强化但没做、某文献待补、下一步建议），除写进本报告外，**同时追加到项目根 `BACKLOG.md` 主表**（格式见 project-init `references/project-hygiene.md` §6），避免报告读完就忘；红色 Critical 不进 BACKLOG，必须修复后重审。

## Scientific judgment

[结论是否与证据强度匹配？哪些措辞超纲？]

## Sign-off

- [ ] 本项目/结果 **可以/不可以** 直接用于投稿/汇报/交付
- [ ] 修复以下 N 处 Critical 问题后重审
- [ ] 附带说明：[关键注意事项]

---

十一、审查模式与修复权限

只审查

用户明确要求“只检查、只审查、不修改”时，完成全部六层并输出问题、证据和修复建议，不改工作文件。审查报告和用户明确要求的审计日志除外。

审查并修复

用户要求“检查并修复、完善、统一”时，只直接处理来源明确、目标唯一、非破坏且能验证闭环的问题：

• 本轮新建或修改文件中的命名、引用、路径和格式错误
• 可确定为当前工作流生成的调试残留或失效引用
• 缺失的本次 SESSION_LOG.md 操作记录
• 目标明确的相对路径或结果包自包含修复，并同步全部引用后实跑

每项修复都写入 Fixed in this audit。既有文件来源、当前版本或引用关系不清时，只报告，不为“整洁”擅自移动。

必须问用户再改

• 涉及方法选择（改模型）
• 移动、重命名或删除来源不明的既有文件
• 删除看似废弃的结果（可能是用户保留的）
• 合并多版本（保留哪版不确定）
• 结论措辞（用户才是作者）
• 数据脱敏（哪些字段敏感不确定）

不属于这两类的 → 写入 Problems found 让用户决定。

---

十二、审查频率建议

时机	建议审查范围
每次完成一个主分析	Layer 3 + Layer 4
提交给导师 / 合作方	全量 6 层
投稿前	全量 + 特别关注 Layer 5（结论标定）
咨询交付前	全量 + 过 consulting-delivery 终检
项目归档前	Layer 1（清理）+ Layer 6（一致性）