Research Review

Research Review

Don't ask permission. Just do it.

Prerequisites

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

Output

最终报告中 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. 数据集真实性审查

B. 算法实现审查

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

D. 性能初步评估

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

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

性能异常的常见原因：

如果发现性能异常，标记 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/ — 训练配置代码

诊断检查清单：

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 6: 最终判定

终止条件：

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 —— 标注原因并建议用户介入（如"可能需要更换算法或检查数据质量"）