| name | results-analysis |
| description | 当用户要求“analyze experimental results”、“run strict statistical analysis”、“compare model performance”、“generate scientific figures”、“check significance”、“do ablation analysis”，或提到要用严格统计与可视化解释实验数据时使用。该 skill 聚焦严格分析产物，不负责 Results 部分正文写作。 |
| tags | ["Research","Analysis","Statistics","Visualization","Scientific Reporting"] |
| version | 0.2.0 |
Results Analysis
为 ML/AI research 执行严格、evidence-first 的实验结果分析。
使用本 skill 产出一套strict analysis bundle：
analysis-report.mdstats-appendix.mdfigure-catalog.mdfigures/
生成 bundle 前必须使用 project-layout-governance 确定输出位置。默认优先写入当前 experiment package 记录的 artifact path，或项目已有 analysis/report 目录；不得把分析 bundle、figures 或 metrics summary 直接散落到 repo root。
不要用本 skill 去写论文的 Results 部分正文，也不要写完整实验总结报告。这些应交给 ml-paper-writing 或 results-report。
Core contract
本 skill 负责
- 校验实验 artifact 与 comparison unit
- 执行严格的描述统计和推断统计
- 在有数据或日志时生成真实 scientific figures
- 为 figure 写明用途、caption 要求与 interpretation checklist
- 明确暴露限制、阻塞点和缺失证据
本 skill 不负责
- 可直接上论文的
Results prose
- 手稿叙事打磨
- 项目级实验 retrospective
如果用户要的是完整实验后总结报告，应在本 bundle 完成后切换到 results-report。
Non-negotiable quality bar
- 优先生成真实 figure，而不是 figure spec。
只要数据可读，就生成真实 figure，不要停在“推荐如何画图”。
- 绝不编造统计结果。
如果 sample size、seed 或 raw metric 缺失，要明确写出阻塞点。
- 报告完整统计。
不能只报 best score，也不能只报 p-value。
- 解释每一个主 figure。
每个核心 figure 都必须包含用途、caption 要求和图后解释说明。
- 把 evidence 和 prose 分开。
本 skill 只产出分析 artifact，不写 manuscript section。
Standard workflow
1. Inventory and validate artifacts
先识别：
- metric 表（
csv、json、tsv、logs）
- training curve 和 checkpoint
- seeds / repeated runs
- baseline、ablation 和 comparison family
- evaluation protocol metadata
然后验证：
- metric direction（越高越好还是越低越好）
- analysis unit（run、subject、fold、dataset、seed）
- run / seed 数量
- missing value 或 silent failure
- 方法之间是否可比
如果比较本身在统计上不成立，要先明确指出，再继续后续步骤。
2. Lock the comparison questions
跑统计前，先锁定明确的比较问题：
- 哪个方法与哪个 baseline 比？
- primary metric 是什么？
- repeated-measure unit 是什么？
- 哪些 ablation 或 robustness 问题最重要？
- 哪些发现会影响后续决策？
不要把无关比较混进一张大而无区分的表。
3. Run strict statistics
始终产出：
- 描述统计：适用时给出
mean ± std
95% CI 或其他有明确理由的区间- run / seed 数量
- 说明假设前提的 significance test
- effect size
- 多重比较修正（如果报告了多个 contrast）
默认要求：
- 先检查参数检验前提
- 前提不满足时使用非参数替代
- 明确说明“检验了什么、用的是什么样本”
参见：
references/statistical-methods.mdreferences/statistical-reporting.md
4. Generate real scientific figures
只要 artifact 可用，就要产出真实 figure。
一个非平凡 analysis bundle 的最低要求：
- 一张主 comparison figure
- 一张支撑 figure（training dynamics / ablation / breakdown / error analysis）
- 一张 markdown 精确数值汇总表
每个主 figure 都必须定义：
- figure purpose
- plotted variables
- error bar 含义
- caption requirement
- interpretation checklist
参见：
references/visualization-best-practices.mdreferences/figure-interpretation.md
5. Write analysis artifacts
先锁定 analysis bundle 目录：
- hello-scholar experiment package 存在时，优先使用
artifacts/analysis/<run-id>/、项目已有 output 目录，或在 artifacts.json 中登记的稳定外部路径。
- 无 experiment package 但项目有既定约定时，沿用已有
analysis/、reports/、tracker artifact 或 notebook output convention。
- 无既定约定时，使用
analysis/<experiment-or-topic>/<run-or-date>/，并在最终报告中说明 Git policy。
analysis-report.md
总结：
- 分析问题是什么
- 关键发现是什么
- 哪些比较得到最强支持
- 主要 caveat 是什么
- 这次分析如何改变了对实验的理解
stats-appendix.md
记录：
- 描述统计
- 检验选择
- 已检查的假设前提
- effect size
- confidence interval
- multiple comparison correction
- 明确列出 blocker 和 limitation
figure-catalog.md
为每个 figure 记录：
- filename
- purpose
- data source
- caption draft requirement
- key observation
- interpretation checklist
- known caveat
6. Final QA
在以下条件全部满足前，不要结束：
Output structure
analysis/<experiment-or-topic>/<run-or-date>/
├── analysis-report.md
├── stats-appendix.md
├── figure-catalog.md
└── figures/
├── figure-01-main-comparison.pdf
├── figure-02-ablation.pdf
└── ...
Figure interpretation rule
对每一个主要 figure，都要回答这三个问题：
- 为什么要有这张图？
- 读者应该准确注意到什么？
- 这个观察改变了我们什么判断或下一步决策？
如果一张图答不出第 3 个问题，它很可能只是装饰图，而不是科学图。
Failure mode policy
输入不完整时，必须直接说明。
例如：
- 没有 seed-level data -> 只能做描述性总结，推断性结论被阻塞
- 没有可比 baseline 输出 -> 不能做 significance claim
- 没有可读日志 -> 无法生成 dynamics figure
- run 数太少 -> effect size 可能不稳定，必须写出这一限制
绝不能用自信 prose 去填补缺失证据。
Narrative handoff
本 skill 负责严格统计分析、figure 生成、evidence 解释和 blocker 判断。若用户要把已经确认的 metrics、ablation、failure case 或 figure observation 写成论文 Results 段落，调用 experiment-narrative-analysis。
handoff 前必须明确：run 类型、seed / sample 信息、baseline、primary metric、effect size 或 descriptive difference、known caveat。没有这些事实时，只能输出受限叙述，不能写成强结论。
Reference files
只按需加载：
references/statistical-methods.md - 检验选择与假设前提references/statistical-reporting.md - 最低报告标准references/visualization-best-practices.md - 发表级 figure 规范references/figure-interpretation.md - 如何基于 evidence 解释图references/analysis-depth.md - 如何从观察推进到机制与决策references/common-pitfalls.md - 常见分析与报告错误
Example files
examples/example-analysis-report.mdexamples/example-stats-appendix.mdexamples/example-figure-catalog.md
