analyze-results

# Analyze Results Command

执行 **blocker-first 实验后分析 + 报告工作流**。

这是用户默认应该使用的入口，但它不是无条件“一键成稿”。它必须先判断证据是否足够，再决定进入 strict analysis、read-only audit、figure generation 或 results report。

如果你只是想“跑严格统计和科研图，不写总结报告”，才单独走 `results-analysis`。

## 目标

此命令负责把一次实验结果处理成两层产物：

### Phase 1: strict analysis bundle
- 严格统计分析
- 真实科研图
- figure interpretation checklist
- 可追溯的统计附录

### Phase 2: complete results report
- 完整实验总结报告
- 逐图解释与结论串联
- 面向决策的 next actions
- 如已绑定 Obsidian，则自动写回知识库

换句话说，`/analyze-results` 不只是“分析”，而是：

> **先做 evidence-first analysis，再基于证据生成完整实验报告。**

## 默认编排

命令默认按以下顺序执行：

0. **Blocker-first gate**
   - 锁定 primary question、primary metric、unit of analysis、seed/run/fold/subject 数、raw provenance、comparison family
   - 如果现有 stats table 的 p-value、interpretation、test method、unit of analysis 或 comparison family 互相矛盾，先 quarantine 该统计文件
   - 如果这些信息不足，先输出 blocker summary 或 read-only audit，不生成完整报告
1. **定位输入**
   - 找到实验目录、CSV/JSON、日志、图表原料与比较对象
2. **Phase 1 严格分析**
   - 使用 `results-analysis`
   - 当用户要求 no-write / audit，或输入不足以生成分析产物时，只输出 valid/invalid statistics、claim candidates 和 blockers
3. **Phase 2 完整报告**
   - 使用 `results-report`
   - 只在 Phase 1 产物包含 `analysis-report.md`、`stats-appendix.md`、`figure-catalog.md` 和必要 provenance 时生成完整实验总结报告
4. **知识库回写**
   - 如果当前 repo 已绑定 Obsidian project memory，则写回 `Results/Reports/`、相关 `Experiments/`、`Daily/` 和 project memory
5. **显式报告 blocker**
   - 若统计输入不足、无法画图或命名信息缺失，必须说明阻塞点，不能伪造结论

## 使用方法

### 基本用法

```bash
/analyze-results
```

### 指定实验目录

```bash
/analyze-results path/to/experiment_dir
```

### 指定分析类型

```bash
/analyze-results path/to/results comparison
```

### 指定报告用途与轮次

```bash
/analyze-results path/to/results full transfer-summary 3 freezing
```

## 参数说明

| 参数 | 说明 |
|------|------|
| `data_path` | 实验结果路径，可为目录、CSV、JSON 或日志 |
| `analysis_type` | `full` / `comparison` / `ablation` / `visualization` / `audit` |
| `purpose` | 报告用途 slug；默认自动推断，无法推断时需显式说明 |
| `round` | 实验轮次；用于报告命名，未知时允许暂用 `r00` 并注明 |
| `experiment_line` | 实验线 slug，如 `freezing`、`contrastive-adversarial` |

## 分析类型

| 类型 | 说明 | Phase 1 重点 | Phase 2 重点 |
|------|------|--------------|--------------|
| `full` | 完整严格分析（默认） | 完整统计 + 主图 + supporting figure | 完整实验总结报告 |
| `comparison` | 模型对比 | 显著性检验 + effect size + 主对比图 | 哪个方案更值得继续 |
| `ablation` | 消融实验 | 组件贡献分析 + 稳定性分析 | 哪个组件真正改变了结果 |
| `visualization` | 图表优先 | 高质量科研图 + 图表解释 | 图驱动的结果复盘 |
| `audit` | 只审查证据是否足够 | valid/invalid statistics、claim candidates、blockers | 不生成完整报告 |

## 输出产物

### Phase 1 输出

```text
analysis-output/
├── analysis-report.md
├── stats-appendix.md
├── figure-catalog.md
└── figures/
```

### Phase 2 输出

```text
Results/Reports/
└── YYYY-MM-DD--{experiment-line}--r{round}--{purpose}.md
```

If the blocker-first gate fails, the valid output is a blocker summary or audit note instead of a report:

```text
analysis-output/
└── blocker-summary.md
```

报告标题默认遵循：

```text
{Experiment Line} / Round {N} / {Purpose} / {YYYY-MM-DD}
```

## 执行规则

### 统计与图表
- 必须优先生成真实科研图，而不是只写 visualization specs
- 必须报告样本单位、seed/run 数、`95% CI`、effect size、multiple-comparison handling
- 假设不满足时必须改用 non-parametric fallback 或显式说明不能做强推断
- 如果 unit of analysis、primary metric、seed/fold/raw provenance 不清楚，不能生成显著性 claim 或 winner claim
- 如果统计表内部解释和数值矛盾，必须 quarantine；不能把矛盾统计写进报告或图注
- 当用户明确要求 audit/no-write，只做 read-only audit，不生成图和报告文件

### 报告生成
- 报告必须基于 Phase 1 的真实证据，而不是凭印象总结
- 报告必须覆盖：main findings、statistical validation、figure-by-figure interpretation、negative results、next actions
- 报告默认是**内部实验总结报告**，不是论文 `Results` section
- 如果缺少完整 analysis bundle，只能写 blocker summary；不能用 polished prose 替代缺失统计

### Obsidian 写回
如果 repo 已绑定 Obsidian knowledge base，则至少执行：
- 新建/更新 `Results/Reports/{report-name}.md`
- 回链对应 `Experiments/` note
- 若结论已稳定，更新 canonical `Results/` note
- 追加当天 `Daily/YYYY-MM-DD.md`
- 更新 `.claude/project-memory/<project_id>.md`

## 何时不用这个命令

以下场景不必默认使用 `/analyze-results`：

1. **你只要统计和图，不要实验总结报告**
   - 直接用 `results-analysis` 生成 Phase 1 strict analysis bundle
2. **你已经有 analysis bundle，只差最终报告**
   - 直接用 `results-report`
3. **你要写论文 Results section**
   - 不应由本命令直接替代 manuscript writing workflow

## 集成关系

- **Primary user entrypoint**: `/analyze-results`
- **Phase 1 skill**: `results-analysis`
- **Phase 2 skill**: `results-report`

## 成功标准

完成后至少应满足：
- blocker-first gate 已完成，并明确说明是否可以进入报告阶段
- 若证据充足，有 strict analysis bundle 和命名规范正确的 results report
- 若证据不足，有 blocker summary / audit note，且没有伪造图表、统计或结论
- 图表与文字解释一致
- blocker 与限制被明确写出
- 若 repo 绑定 Obsidian，只有在证据足够时才完成最小写回