research-review

name	research-review
description	[Read when prompt contains /research-review]
metadata	{"openclaw":{"emoji":"🔍","requires":{"bins":["python3","uv"]}}}

Research Review

Don't ask permission. Just do it.

Prerequisites

File	Source
ml_res.md	/research-implement
project/	/research-implement
plan_res.md	/research-plan
survey_res.md	/research-survey

If ml_res.md is missing, STOP: "需要先运行 /research-implement 完成代码实现"

Output

File	Content
iterations/judge_v{N}.md	每轮审查报告

最终报告中 verdict: PASS 表示审查通过。

---

Workflow

Step 1: 审查代码

读取以下内容：

• plan_res.md — 每个组件的预期
• survey_res.md — 核心公式
• project/ — 实际代码
• ml_res.md — 执行结果

Step 2: 提取原子性概念清单

⚠️ 这是 Novix Judge Agent 的核心机制 — 逐一核对每个原子性学术概念。

从 survey_res.md 的"关键公式汇总"和"核心方法对比"中，提取所有需要在代码中实现的原子性学术概念（每个公式、每个核心组件都是一个概念）。

为每个概念记录：

• 概念名称（如 "Multi-Head Attention", "Contrastive Loss", "Batch Normalization"）
• 对应公式（LaTeX 格式）
• 预期代码位置（根据 plan_res.md 推断）

示例清单：

原子性概念清单（从 survey_res.md 提取）：
1. Multi-Head Attention — $Attention(Q,K,V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$ — 预期在 model/attention.py
2. Layer Normalization — $LN(x) = \gamma \frac{x - \mu}{\sigma} + \beta$ — 预期在 model/layers.py
3. Residual Connection — $y = F(x) + x$ — 预期贯穿所有模型组件
...

Step 3: 逐项检查

A. 数据集真实性审查

检查项	方法
数据集是否真实拉取	检查 data/ 目录下是否有实际数据文件（非空文件），检查下载脚本/代码是否真正执行了网络请求或本地读取
数据加载代码正确性	实际执行数据加载代码，验证 shape、dtype、样本数是否与 plan 一致：python3 -c "from data.dataset import *; ds = ...; print(len(ds), ds[0])"
Mock 数据标注	搜索 # MOCK DATA 注释；如果使用 mock 数据但未声明，标记为 NEEDS_REVISION

B. 算法实现审查

检查项	方法
原子性概念逐一核对	对照 Step 2 的概念清单，逐个检查：该概念是否在代码中有对应实现？公式翻译是否正确？维度/参数是否一致？每个概念标注 ✓ 或 ✗ 并记录代码位置
Loss 函数正确	对比 plan Training Plan vs training/loss.py，验证数学公式是否正确翻译为代码
评估指标正确	对比 plan Testing Plan vs testing/，确认指标计算逻辑无误
关键算法未被简化	检查 plan 中的核心创新点是否被完整实现，而非用简化/占位逻辑替代

C. 算力与执行合理性审查

检查项	方法
执行用时合理	读取 ml_res.md 中 [RESULT] elapsed= 值，根据数据集规模 + 模型参数量 + 设备（CPU/GPU）判断用时是否合理。过短（如万级数据集 <1s）可能说明数据未真正加载或训练未真正执行
[RESULT] 行存在	检查 ml_res.md 中的数值来源，确认非编造
Loss 合理	非 NaN/Inf，有下降趋势（epoch 1 loss > epoch 2 loss）
数据管道匹配 plan	对比 plan Dataset Plan vs data/ 实现，batch size、预处理步骤一致

D. 性能初步评估

⚠️ 关键新增 — 防止"代码正确但效果很差"的算法被放行。

从 ml_res.md 提取 2 epoch 验证结果，评估算法有效性：

检查项	判定标准	诊断
Loss 下降幅度	计算 reduction = (epoch1_loss - epoch2_loss) / epoch1_loss * 100%	<5% → 可能学习率过小、架构有问题或数据未正确处理
Loss 稳定性	检查 epoch 1 和 epoch 2 的 loss 波动	震荡 >20% → 可能学习率过大或 batch size 不当
Metrics 合理性	对比任务的随机 baseline（分类: 1/num_classes，回归: 数据方差）	接近随机（±10%）→ 模型未真正学习，可能特征无效或架构过简单
与 plan 预期对比	如果 plan_res.md 中有性能预期，对比实际结果	低于预期 30% → 需要反思算法设计或超参数设置

性能异常的常见原因：

症状	可能原因	验证方法
Loss 几乎不变（<2%）	学习率过小	检查 plan_res.md 中 lr 值，对比 survey_res.md 中 baseline lr
Loss 震荡剧烈（>30%）	学习率过大	同上
Loss 下降但 metric 不变	模型过简单或特征无效	检查模型参数量；检查数据预处理是否正确（归一化、标准化）
Accuracy 接近随机	数据标签错误或未正确加载	重新验证数据加载代码，打印样本检查
Loss=NaN/Inf	梯度爆炸、数值不稳定	检查是否有 Batch/Layer Normalization；检查 lr 是否过大

如果发现性能异常，标记 verdict: NEEDS_ALGORITHM_REVIEW（不同于 NEEDS_REVISION）。

Step 4: 写入审查报告

写入 iterations/judge_v1.md：

# Review v1

## Verdict: PASS / NEEDS_REVISION / NEEDS_ALGORITHM_REVIEW

## Checklist

### 数据集
- [x/✗] Dataset actually downloaded/loaded (not empty or placeholder)
- [x/✗] Data loading code produces correct shape/dtype/count
- [x/✗] No undeclared mock data

### 算法实现 - 原子性概念核对

**逐一核对 Step 2 提取的每个学术概念：**

| 概念 | 公式 | 代码位置 | 结果 | 备注 |
|------|------|----------|------|------|
| {概念名} | $...$ | `model/xxx.py:L42` | ✓/✗ | {正确实现/公式错误/缺失/简化为占位符} |
| ... | ... | ... | ... | ... |

### 算法实现 - 整体检查
- [x/✗] Loss function correctly implements the math
- [x/✗] Key algorithm components fully implemented (no simplified placeholders)
- [x/✗] Evaluation metrics correct

### 算力与执行
- [x/✗] Execution time reasonable for data scale + model size + device
- [x/✗] Training loop proper (loss decreasing)
- [x/✗] Results are from real execution (not fabricated)

### 性能初步评估（新增）

**2-Epoch Validation Results** (from `ml_res.md`):
- Epoch 1 loss: {value}
- Epoch 2 loss: {value}
- Loss reduction: {percent}% (expected: >10% for initial epochs)
- Metric (e.g., accuracy): {value} (random baseline: {baseline_value})

**Performance Assessment**:
- [x/✗] Loss decreasing adequately (reduction >5%)
- [x/✗] Metrics above random baseline (+10% or more)
- [x/✗] No severe oscillation (<20% variance)
- [x/✗] Meets plan expectations (if performance target specified in plan_res.md)

**Diagnosis** (if performance issues):
- **Symptom**: {what's wrong - e.g., "Loss reduction only 0.9%, far below 10% expected"}
- **Likely cause**: {diagnosis - e.g., "Learning rate too small (lr=1e-5, survey baseline=1e-3)"}
- **Evidence**: {supporting evidence - e.g., "survey_res.md Table 2 shows all baselines use lr=1e-3"}

## Issues (if NEEDS_REVISION)
1. **{issue}**: {description} → **Fix**: {specific fix instruction}
2. ...

## Algorithm Review Suggestions (if NEEDS_ALGORITHM_REVIEW)

**按优先级排序的改进建议**（只调整超参数/训练配置，不改核心算法）：

1. **{建议名称}**（最可能有效）
   - **What to change**: {具体修改内容}
   - **Where**: {文件路径和代码位置}
   - **Expected improvement**: {预期效果}

2. **{次要建议}**
   - ...

**Note**: 如果尝试所有建议后仍无改善，可能需要重新考虑算法选择或数据质量。

Step 5a: 代码修复迭代（如果 NEEDS_REVISION）

⚠️ 防偏移机制：每轮迭代都重新读取原始设计文档，确保修改方向正确。

循环最多 3 次：

1. 读取 judge_v{N}.md 的修改建议
2. 防偏移检查：重新读取 survey_res.md 和 plan_res.md
   • 对照原始学术设计目标
   • 确保修改不是为了"绕过审查"而偏离学术严谨性
   • 确认修改符合 survey 中的公式定义和 plan 中的设计意图
3. 修改 project/ 中的代码（修复 bug、补全缺失实现）
4. 重新执行：

   cd project && source .venv/bin/activate && python3 run.py --epochs 2
   

5. 读取执行输出，验证修复
6. 重新执行 Step 2-4（提取概念清单 → 逐项检查 → 写报告），写入 judge_v{N+1}.md
7. 如果 PASS 或 NEEDS_ALGORITHM_REVIEW → 停止；否则继续

Step 5b: 算法反思与调优（如果 NEEDS_ALGORITHM_REVIEW）

⚠️ 关键新增 — 代码正确但性能不佳时的改进循环。

前提：代码实现正确（所有原子性概念 ✓），但 2 epoch 验证显示性能异常。

循环最多 2 次：

5b.1 性能诊断

重新读取以下材料进行诊断：

• ml_res.md — 2 epoch 验证的具体数值
• survey_res.md — baseline 方法的超参数设置（特别是学习率、batch size）
• plan_res.md — 当前实现的超参数配置
• project/run.py 和 project/training/ — 训练配置代码

诊断检查清单：

症状	诊断步骤	常见原因
Loss 下降 <5%	对比 plan lr vs survey baseline lr	lr 过小（如 plan=1e-5 但 survey=1e-3）
Loss 震荡 >20%	同上 + 检查 batch size	lr 过大或 batch size 过小
Accuracy 接近随机	检查数据预处理代码、检查 loss 是否下降	数据归一化缺失、特征错误、模型过简单
Loss=NaN/Inf	检查是否有 normalization、检查 lr	梯度爆炸、数值不稳定

5b.2 生成改进建议

基于诊断结果，生成按优先级排序的改进建议。

改进范围限制：

• ✅ 允许：调整超参数（lr、batch size、epochs、optimizer、scheduler）
• ✅ 允许：修改训练配置（添加 warmup、gradient clipping、weight decay）
• ✅ 允许：修复数据预处理问题（添加归一化、标准化）
• ❌ 禁止：修改核心算法逻辑（模型架构、loss 函数数学公式）

建议格式（写入 judge_v{N}.md 的 "Algorithm Review Suggestions" 部分）：

1. **调整学习率**（优先级：高，预期改善：显著）
   - **当前值**: lr=1e-5 (from plan_res.md)
   - **建议值**: lr=1e-3 (from survey_res.md Table 2, all baselines use 1e-3)
   - **修改位置**: `project/run.py:L15` — `optimizer = Adam(lr=1e-3)`
   - **理由**: Loss 下降仅 0.9%，远低于正常 10%+，高度怀疑 lr 过小

2. **添加数据归一化**（优先级：中，预期改善：中等）
   - **检查**: `project/data/dataset.py` 是否有归一化
   - **建议**: 添加 `transforms.Normalize(mean=[0.5], std=[0.5])`
   - **理由**: 如果输入数据范围 [0,255]，模型收敛会很慢

5b.3 执行改进并验证

1. 根据建议逐项尝试（从优先级高的开始）
2. 每次修改后：

   cd project && source .venv/bin/activate && python3 run.py --epochs 2
   

3. 读取新的执行输出，对比改进前后：
   • Loss reduction 是否提升？（如 0.9% → 12%）
   • Metrics 是否改善？（如 accuracy 12% → 34%）
4. 记录每次尝试的结果到 judge_v{N+1}.md 的 "Algorithm Review Iterations" 部分：

## Algorithm Review Iterations

### Iteration 1
- **Change**: Increased lr from 1e-5 to 1e-3
- **Result**:
  - Loss reduction: 0.9% → 12.3% ✓ (improvement: +11.4%)
  - Accuracy: 12% → 34% ✓ (improvement: +22%)
- **Conclusion**: Learning rate was the bottleneck. Issue resolved.
- **New verdict**: PASS ✓

### Iteration 2 (if needed)
- ...

5b.4 判定

• 改善显著（loss reduction 提升 >5%）→ verdict: PASS，停止
• 改善微小（<2%）→ 继续下一个建议或下一轮
• 2 轮后仍无改善 → verdict: BLOCKED，标注原因（如"所有超参数调整均无效，可能需要重新选择算法或检查数据质量"）

---

Step 5a vs 5b 的区别：

	Step 5a (NEEDS_REVISION)	Step 5b (NEEDS_ALGORITHM_REVIEW)
触发条件	代码有 bug、实现错误	代码正确但性能不佳
修改范围	核心算法代码	超参数和训练配置
迭代次数	3 次	2 次
目标	正确性	有效性

Step 6: 最终判定

终止条件：

场景	判定	说明
所有 checklist ✓ + 性能合理	PASS	交付给 research-experiment
Step 5a 3 轮后仍有 bug	BLOCKED - Code Issues	列出剩余问题，等待用户介入
Step 5b 2 轮后性能仍异常	BLOCKED - Performance Issues	标注尝试过的改进和结果，建议用户重新考虑算法选择或数据质量

---

Rules

审查标准

1. 审查必须逐项对照 plan，不能只看"代码能跑"
2. 每个 issue 必须给出具体的修复指令（不是"请改进"）
3. 验证修复后必须重新执行代码并检查输出
4. PASS 的前提：所有 checklist 项通过 + 性能初步评估合理（不仅仅是"有下降"）
5. 数据集必须验证真实性 —— 实际执行数据加载代码，确认有真实数据（哪怕是小规模）；纯随机 tensor 不算
6. 执行时间必须与算力匹配 —— 2 epoch 训练时间过短（数据量 >1000 却 <2s）说明数据未加载或训练是空循环
7. 算法实现必须完整 —— plan 中标注的核心创新点必须逐一检查，不能被简化为 nn.Linear 占位
8. 原子性概念逐一核对（Novix Judge 机制） —— Step 2 提取的每个概念都必须在 judge 报告的表格中有对应行，标注 ✓ 或 ✗
9. 防偏移（每轮迭代必须重新对齐） —— Step 5a/5b 每轮修改前必须重新读取 survey_res.md 和 plan_res.md，确保不偏离原始设计目标

性能评估（新增）

10. 性能初步评估是强制项 —— Step 3D 必须执行，不能跳过
11. Loss 下降幅度有最低要求 —— 2 epoch 验证的 loss reduction <5% 必须标记为性能异常
12. Metrics 必须超过随机 baseline —— 分类任务 accuracy 接近 1/num_classes（±10%）视为"模型未学习"
13. 性能异常触发算法反思 —— 代码正确但性能不佳时，必须进入 Step 5b 尝试调优，不能直接 PASS

算法反思（新增）

14. Step 5b 只调超参数，不改算法 —— 禁止修改核心算法逻辑、模型架构、loss 函数公式
15. 改进建议必须有依据 —— 每个建议必须引用 survey_res.md 或 plan_res.md 中的具体内容
16. 改进效果必须量化 —— 每次尝试后必须记录改善幅度（如 "loss reduction +11.4%"），不能只说"有改善"
17. 2 轮算法反思后仍无改善视为 BLOCKED —— 标注原因并建议用户介入（如"可能需要更换算法或检查数据质量"）