update-study

更新研究 - 学术级实验报告生成

这是一项通过分析实验日志生成学术论文级实验报告的技能。 包括 matplotlib 可视化、Executive Summary、实现结构、结果解读、改进方案以及 LaTeX PDF 转换。

核心功能

1. 增量检测 - 仅分析新实验（跳过已记录的实验）
2. 数据提取 - 从 W&B/日志文件中提取指标时间序列，并使用 pandas DataFrame 进行结构化
3. 自动绘图 - 基于 matplotlib 生成对比图、趋势面板和条件分析图
4. 迭代写作循环 - 学术论文级质量改进循环（>=80 分通过）
5. 零幻觉 - 在日志级别进行交叉验证
6. LaTeX PDF 导出 - 转换为 LaTeX 并生成包含 Figure 的 PDF

用法

/update-study <log_path(s)> <study_md_path>

• log_path(s)：实验日志文件路径（可用空格分隔多个路径，包括 W&B export CSV）
• study_md_path：要更新的 study markdown 文件路径

参数解析

如果 $ARGUMENTS 的最后一个参数是 .md 文件，则将其解析为 study 文件，其余参数解析为日志文件。

예시:
  /update-study logs/exp1.log results/study.md
  → log_files: ["logs/exp1.log"]
  → study_file: "results/study.md"

  /update-study logs/exp1.log logs/exp2.log memgen_ablation_study.md
  → log_files: ["logs/exp1.log", "logs/exp2.log"]
  → study_file: "memgen_ablation_study.md"

---

报告模板

最终报告遵循以下结构，并保持学术论文级格式。

# {Title} Experiment Report

**Author**: {name}  **Date**: {date}  **Project**: {project}

## Executive Summary

| Task | Key Metric | Baseline | Proposed | Difference |
|------|-----------|----------|----------|------------|
| {task_a} | {metric} | {baseline_val} | {proposed_val} | {delta} |
| {task_b} | {metric} | {baseline_val} | {proposed_val} | {delta} |

{1-2 sentence overall conclusion}

## 1. Implementation

### 1.1 Overview

{실험의 목적과 접근 방식을 Definition-First 원칙으로 기술}

### 1.2 Implementation Structure

{핵심 코드 구조를 코드 스니펫으로 제시}

```python
class ProposedModule(nn.Module):
    """모듈 설명 - 무엇을, 왜 하는지"""
    def __init__(self, config):
        ...
    def forward(self, x):
        ...

2. 实验结果

2.1 {Task A}：{核心结果一句话总结}

{结果表格 + Figure 引用 + 解读}

Figure 1 解读：{Figure 中观察到的模式、含义以及与 baseline 的差异}

2.2 {Task B}：{核心结果一句话总结}

{相同结构}

2.3 {分析标题}：{交叉分析或相关性分析}

{对多个实验/条件进行比较分析}

2.4 {局限性分析标题}

{分析实验结果中发现的局限，以及与预期不符的结果}

2.5 实验设置

参数	值
模型	{model_name}
数据集	{dataset}
轮数	{N}
学习率	{lr}
批量大小	{batch_size}
硬件	{gpu_info}

3. 改进方案

3.1 {Method A}

问题：{当前结果中发现的具体问题及其数值依据}

解决方案：{提出的解决方法及其依据}

# 구현 예시
class ImprovedModule(nn.Module):
    def __init__(self, config):
        ...

预期效果：{预期的改进效果及其依据}

3.2 {Method B}

{相同结构：Problem → Solution → Code → Expected Effect}

4. 局限性

• {局限 1}：{具体说明 + 影响范围}
• {局限 2}：{具体说明 + 影响范围}
• {局限 3}：{具体说明 + 影响范围}

5. 结论

{主要发现总结、贡献及意义}

6. 后续实验

E{N}：{实验名称}

• 测试：H{N}
• 配置变更：

  {parameter}: {new_value}  # was: {old_value}
  

• 预期：{假设成立时预期得到的结果}

E{N+1}：{实验名称}

• 测试：H{N+1}
• 配置变更：

  {config_changes}
  

• 预期：{预测}

参考文献

• {相关论文/资料列表}

---

## Workflow Overview

阶段 0：增量检测 ├── 扫描 logs/ ├── 解析现有 study（识别已分析的实验） └── 生成新实验列表 → 如果没有新实验，则输出 "No new experiments" 并结束

阶段 1：文件验证 ├── 确认日志文件存在 └── 读取 study.md

阶段 2：数据提取（新增） ├── 从日志/W&B 文件中提取指标时间序列 ├── 使用 pandas DataFrame 进行结构化 └── 指标：accuracy、loss、ratio、entropy 等

阶段 3：绘图（新增） ├── 调用 scripts/generate_plots.py ├── 对比训练曲线（Filter OFF 与 ON 风格） ├── 指标趋势（多子图面板） ├── 按条件生成对比图 └── 输出：将 PNG 保存到 figures/ 目录

阶段 4：解读 + 写作（扩展） ├── 调用 experiment-interpreter Agent ├── 生成 Executive Summary 对比表格 ├── 撰写每个 Figure 的解读 ├── 编写 Proposed Improvements 部分（Problem → Solution → Code → Expected Effect） ├── 撰写 Limitations、Conclusion、Next Experiments └── 写作质量循环（>=80 分，最多重复 3 次）

阶段 5：验证 ├── 调用 experiment-verifier Agent ├── 验证数字准确性 └── 验证逻辑一致性

阶段 6：导出（扩展） ├── 最终确定 Markdown ├── 转换为 LaTeX 并包含 Figure（scripts/export_latex_pdf.py） ├── 生成 PDF └── 回退方案：scripts/export_pdf.py（现有 pandoc/weasyprint 方式）

---

## Phase 0: Incremental Detection

### Step 0.1: 로그 디렉토리 스캔

1. 生成 logs/ 目录中的所有日志文件列表

   • 模式：_train.log、_eval.log、.log、.csv（W&B export）
   • 按文件修改时间排序

2. 与输入的日志文件列表进行交叉核对

### Step 0.2: 기존 Study 분석

从现有 study.md 中识别已记录的实验：

1. 搜索实验标题模式：

   • ### E{N}: 或 ### Experiment:
   • ## Experiment {N}:

2. 提取日志文件引用：

   • [*_train.log:*] 格式的来源标注
   • Source: 列中的文件名

3. 构建已记录实验列表： documented_experiments = { "evolve_h_only_train.log", "cross_attn_train.log", ... }

### Step 0.3: 새 실험 결정

```python
new_experiments = set(input_logs) - set(documented_experiments)

if len(new_experiments) == 0:
    print("No new experiments to analyze")
    print(f"  Already documented: {len(documented_experiments)} experiments")
    exit()  # 종료
else:
    print(f"Found {len(new_experiments)} new experiment(s) to analyze:")
    for exp in new_experiments:
        print(f"  - {exp}")

---

阶段 1：文件验证

步骤 1.1：确认文件

1. 새 실험 로그 파일 존재 확인
   - 각 log_path에 대해 파일 존재 여부 확인
   - 존재하지 않으면 에러 메시지 출력 후 중단

2. study.md 파일 확인
   - 파일이 존재하면 Read tool로 전체 내용 읽기
   - 파일이 없으면 새로 생성할 것임을 안내

3. 로그 파일 요약 정보 추출 (빠른 스캔)
   - 실험 config 파일 경로
   - 실험 모드 (train/evaluate)
   - 최종 metric 라인 위치

步骤 1.2：分析现有 study.md

기존 study.md에서 확인할 사항:
- 이미 기록된 실험 목록
- 비교 가능한 baseline 결과
- 미해결 가설 목록
- 계획된 실험 목록 (이번 실험이 기존 계획에 해당하는지)

---

阶段 2：数据提取

从日志文件和 W&B export 中提取指标时间序列数据并进行结构化。

步骤 2.1：提取指标时间序列

1. 로그 파일 파싱
   - 정규표현식으로 epoch/step별 메트릭 추출
   - 패턴 예시:
     - "Epoch {N}: accuracy={X.XX}, loss={X.XXXX}"
     - "Step {N} | train_loss: {X.XXXX} | eval_acc: {X.XX}"
     - W&B CSV: 컬럼 기반 직접 로드

2. W&B API/CSV 지원
   - wandb export CSV 파일 자동 인식
   - 컬럼명 표준화 (step, epoch, metric_name)

步骤 2.2：使用 pandas DataFrame 进行结构化

# 추출 결과 구조
import pandas as pd

# 각 실험별 DataFrame
df = pd.DataFrame({
    'step': [...],
    'epoch': [...],
    'train_loss': [...],
    'eval_accuracy': [...],
    'learning_rate': [...],
    'grad_norm': [...],
    # 실험별 추가 메트릭
    'ratio': [...],        # 필터링 비율 등
    'entropy': [...],      # 분포 엔트로피 등
})

# 메타데이터
metadata = {
    'experiment_name': '...',
    'config_path': '...',
    'log_path': '...',
    'total_epochs': N,
    'final_metrics': {
        'accuracy': X.XX,
        'loss': X.XXXX,
    }
}

步骤 2.3：目标指标

필수 메트릭 (로그에 존재하는 경우):
- accuracy (eval/test)
- loss (train/eval)
- learning_rate
- grad_norm

선택 메트릭 (실험 유형에 따라):
- ratio (필터링 비율, 압축 비율 등)
- entropy (분포 엔트로피)
- perplexity
- BLEU / ROUGE
- custom metrics (로그에서 자동 감지)

---

第 3 阶段：图表生成

调用 scripts/generate_plots.py，生成基于 matplotlib 的可视化图表。

步骤 3.1：图表类型

1. Training Curve 비교 (필수)
   - X축: epoch 또는 step
   - Y축: loss / accuracy
   - 여러 실험을 한 차트에 오버레이
   - 스타일: "Filter OFF vs Filter ON" 비교 형태
   - 범례, 그리드, 타이틀 포함

2. Metric Trend Panel (필수)
   - Multi-subplot 레이아웃 (2x2 또는 3x2)
   - 각 subplot: 하나의 메트릭 시계열
   - 예: loss, accuracy, grad_norm, learning_rate
   - 실험 간 동일 스케일 사용

3. 조건별 비교 차트 (조건부)
   - Bar chart: 최종 메트릭 비교 (실험별)
   - Grouped bar: 여러 메트릭을 실험별로 그룹화
   - 예: baseline vs proposed 최종 accuracy 비교

4. 분포 차트 (조건부)
   - Histogram: metric 분포 비교
   - Box plot: 실험 간 변동성 비교

步骤 3.2：调用脚本

python scripts/generate_plots.py \
  --data extracted_metrics.json \
  --output-dir figures/ \
  --experiments "exp1,exp2,baseline" \
  --plots training_curve,metric_panel,comparison_bar

步骤 3.3：输出

figures/
  ├── training_curve_comparison.png    # Loss/accuracy 비교 곡선
  ├── metric_trend_panel.png           # Multi-subplot 메트릭 패널
  ├── final_metric_comparison.png      # Bar chart 최종 비교
  └── {custom_name}.png                # 실험별 추가 차트

步骤 3.4：Figure 样式标准

# 학술 논문 수준 matplotlib 설정
import matplotlib.pyplot as plt

plt.rcParams.update({
    'figure.figsize': (10, 6),
    'figure.dpi': 150,
    'font.size': 12,
    'font.family': 'serif',
    'axes.labelsize': 13,
    'axes.titlesize': 14,
    'legend.fontsize': 11,
    'xtick.labelsize': 11,
    'ytick.labelsize': 11,
    'axes.grid': True,
    'grid.alpha': 0.3,
    'lines.linewidth': 2.0,
    'figure.constrained_layout.use': True,
})

# 색상 팔레트 (colorblind-friendly)
COLORS = ['#0072B2', '#D55E00', '#009E73', '#CC79A7', '#F0E442', '#56B4E9']

---

第 4 阶段：解读与撰写

步骤 4.1：调用 Experiment-Interpreter Agent

Task tool 사용:
- subagent_type: "experiment-interpreter"
- prompt:

  "다음 실험 로그와 생성된 Figure를 분석하여
   학술 논문 수준의 실험 보고서를 작성해주세요.

  ## 데이터
  {추출된 DataFrame 요약}

  ## 생성된 Figure 목록
  {figures/ 디렉토리의 PNG 파일 목록과 각 차트 설명}

  ## 로그 파일
  {각 로그 파일의 전체 경로}

  ## 기존 study.md 내용 (비교용)
  {기존 study.md의 결과 요약 테이블}

  ## 이전 검증 피드백 (있는 경우)
  {verifier의 feedback_summary - 첫 iteration에는 없음}

  ## 요구사항
  1. Report Template 구조를 따를 것
  2. Executive Summary 비교 테이블 생성
  3. 각 Figure에 대한 구체적 해석 작성
     - 패턴, 추세, 이상점 기술
     - baseline 대비 차이 설명
     - Figure 번호로 참조 (Figure 1, Figure 2, ...)
  4. Implementation Structure 섹션에 핵심 코드 스니펫 포함
  5. Proposed Improvements: Problem → Solution → Code → Expected Effect
  6. Limitations 섹션: 구체적 한계와 영향 범위
  7. Conclusion: 주요 발견 요약
  8. Next Experiments: 가설과 연결된 구체적 계획
  9. 모든 수치에 출처 표기 (source: filepath:L행번호)
  10. 각 가설은 falsifiable + prediction + falsification 포함
  11. 출력은 Report Template 형식의 markdown

  ## 출력 형식
  references/interpretation-template.md 템플릿을 따르되,
  Report Template의 전체 구조에 맞게 확장해주세요."

步骤 4.2：生成执行摘要

## Executive Summary

| Task | Key Metric | Baseline | Proposed | Difference |
|------|-----------|----------|----------|------------|
| {각 실험 task별 핵심 비교 결과} |

생성 규칙:
- Baseline은 기존 study에 기록된 vanilla/default 결과
- Proposed는 이번 실험의 결과
- Difference는 절대값 + 방향 (+/-) 포함
- 가장 중요한 메트릭 우선 배치

步骤 4.3：撰写 Figure 解读

각 Figure에 대해:

1. Figure 참조 삽입:
   ![Figure N: {descriptive caption}](figures/{filename}.png)

2. 해석 문단 작성 (Topic-First 원칙):
   **Figure N 해석**: {핵심 관찰}. {상세 설명}. {baseline 대비 차이}.
   {가능한 원인/메커니즘 분석}.

3. 해석 품질 기준:
   - 정량적: 수치로 차이를 기술
   - 비교적: baseline 또는 이전 실험과 대비
   - 인과적: 왜 이런 패턴이 나타나는지 가설 제시

步骤 4.4：撰写拟议改进

각 개선안에 대해 4-part 구조:

### 3.N {Method Name}

**Problem**: {실험 결과에서 발견된 구체적 문제}
  - 수치 근거 포함 (source: filepath:L행번호)
  - Figure 참조 포함 (Figure N 참조)

**Solution**: {제안하는 해결 방법}
  - 기존 연구/이론적 근거 제시
  - 구현 방향 설명

```python
# 구현 예시 코드
class ImprovedComponent:
    ...

预期效果：{预期改进效果}

• 定量预测（例如：“预计 accuracy 提升 2-3%p”）
• 说明依据

### Step 4.5: Writing Quality Loop

작성된 초안에 대해 품질 평가 수행:

评估标准（参见 references/quality-criteria.md，更新权重）：

1. 定义优先（25 分）

   • 是否以“X is Y”的形式定义了所有专业术语？
   • 是否在使用新概念前先对其进行定义？

2. 段落主题优先（20 分）

   • 每个段落是否都以核心结果或论点开头？
   • 只读第一句话是否就能了解段落内容？

3. 比较与对照（15 分）

   • 是否将新结果与之前的实验进行了比较？
   • 是否说明了差异的原因或解读？

4. 洞察深度（15 分）

   • 是否超越表面描述，分析了“为什么”？
   • 是否针对出乎预料的结果提出了假设？

5. 尽量少用形容词（5 分）

   • 是否避免了不必要的修饰语？
   • 是否使用具体数值，而非主观表达？

6. Figure 质量（10 分）[新增]

   • 是否为所有 Figure 撰写了解读段落？
   • Figure caption 是否准确描述了内容？
   • 正文中的 Figure 引用是否正确对应？

7. 后续步骤清晰度（10 分）[新增]

   • 后续实验是否与假设明确关联？
   • Config 变更是否具体？
   • 是否给出了预期结果及其依据？

总分：/100 通过标准：>= 80 分

### Step 4.6: Revision (점수 < 80인 경우)

1. [严重：缺少定义]

   • 列出未定义术语
   • 为每个术语补充“X is Y”形式的定义

2. [严重：段落主题在末尾]

   • 按照核心内容 → 说明 → 依据的顺序重组段落

3. [警告：缺少比较]

   • 添加与之前实验的比较表
   • 添加分析差异的段落

4. [警告：洞察浅显]

   • 补充“为什么会出现这样的结果？”分析
   • 强化假设

5. [轻微：形容词过多]

   • “significantly improved” → “+12.5%p”
   • “much faster” → “2.3x speedup”

6. [警告：Figure 缺少解读]

   • 为缺少解读的 Figure 添加解读段落
   • 如果 Caption 不准确，则进行修改

7. [警告：后续步骤含糊]

   • 明确与假设的关联
   • 具体说明 Config 变更

### Step 4.7: Iteration Control

最多迭代 3 次

迭代 1：初稿 → 质量评估 → 修改（如有需要） → Score >= 80：进入第 5 阶段 → Score < 80：收集反馈

迭代 2：修改稿 → 重新评估 → Score >= 80：进入第 5 阶段 → Score < 80：收集反馈

迭代 3：最终修改 → 重新评估 → Score >= 80：进入第 5 阶段 → Score < 80：使用当前最佳版本继续，并报告问题

---

## Phase 5: Verification (experiment-verifier)

### Task Tool 호출

使用 Task 工具：

• subagent_type: "experiment-verifier"

• prompt:

  "请验证以下 study.md 更新内容。

  验证对象（新添加的章节）

  {在第 4 阶段撰写的内容}

  原始日志文件路径

  {各日志文件的完整路径}

  现有 study.md（用于确认是否有变更）

  {现有 study.md 内容}

  生成的 Figure 列表

  {figures/ 目录内容}

  验证要求

  1. 对照原始日志核实所有数值（直接检查文件和行）
  2. 核实执行摘要表格中的数值是否准确
  3. 确认 Figure 解读是否与实际数据一致
  4. 验证解读的逻辑合理性
  5. 确认所有假设是否可证伪
  6. 确认后续实验是否可执行
  7. 确认现有结果是否发生变更
  8. 确认代码片段的语法是否正确

  输出

  请返回 JSON 格式的验证报告。"

### 결과 처리

```python
if verdict == "PASS":
    # Phase 6로 진행
elif iteration < 3:
    # feedback_summary를 Phase 4로 전달
    # interpreter에게 수정 요청
else:
    # 최대 반복 도달
    # 현재 최선 버전 저장
    # 미해결 이슈 사용자에게 보고

---

第 6 阶段：导出

步骤 6.1：定稿 Markdown

1. study.md 최종 내용 저장
2. [NEW] 태그가 포함된 섹션 확인
3. Figure 참조 경로 검증 (figures/*.png 존재 확인)
4. 상대 경로 정규화

步骤 6.2：转换为 LaTeX 并生成 PDF（优先方式）

# scripts/export_latex_pdf.py 사용 (Figure 포함 LaTeX 변환)
python scripts/export_latex_pdf.py \
  study.md \
  study.pdf \
  --figures-dir figures/ \
  --template academic

기능:
- Markdown → LaTeX 변환
- Figure 자동 삽입 (\includegraphics)
- 학술 논문 레이아웃 (twocolumn 옵션 가능)
- TOC (Table of Contents) 포함
- [NEW] 태그 시각적 강조
- 테이블 포맷팅 (booktabs 스타일)
- 코드 블록 문법 강조 (listings/minted)
- 참고문헌 섹션

步骤 6.3：备用 PDF 转换

# LaTeX 변환 실패 시 기존 방식 사용
python scripts/export_pdf.py study.md study.pdf

Fallback 순서:
1. scripts/export_latex_pdf.py (LaTeX + Figure, 최상의 품질)
2. scripts/export_pdf.py → pandoc + LaTeX (Figure 수동 포함)
3. scripts/export_pdf.py → weasyprint (HTML 기반)
4. Markdown만 저장 (PDF 변환 실패 시 경고)

步骤 6.4：完成报告

Update Complete!
  Markdown: study.md
  PDF: study.pdf
  Figures: figures/ ({N}개 PNG)
  New experiments: {N}개
  Writing quality: {score}/100
  Hypotheses: {N}개
  Next experiments: {N}개

---

文档更新规则

仅追加原则

1. 仅追加：在现有内容后添加新章节。禁止修改现有内容。
2. [NEW] 标签：为新添加的实验标注 [NEW] 标签（下次更新时移除）
3. 分隔线：在新实验前插入 --- 分隔线
4. 日期标注：实验执行日期（基于日志时间戳）
5. 格式一致：遵循 Report Template 和 references/interpretation-template.md

[NEW] 标签处理

---

### [NEW] Experiment: {experiment_name} ({YYYY-MM-DD})

...

下次执行 /update-study 时：

1. 移除之前添加的所有 [NEW] 标签
2. 仅为新添加的章节标注 [NEW] 标签

---

进度报告

执行过程中向用户报告状态：

[Phase 0] Incremental Detection...
  Scanned logs/: {N}개 파일
  Already documented: {M}개 실험
  New experiments: {K}개 발견

[Phase 1] File Verification...
  로그 파일 확인: {K}개
  study.md 읽기 완료

[Phase 2] Data Extraction...
  메트릭 추출: {N}개 시계열
  DataFrame 구조화 완료
  메트릭 종류: accuracy, loss, grad_norm, ...

[Phase 3] Plot Generation...
  Training curve comparison: figures/training_curve_comparison.png
  Metric trend panel: figures/metric_trend_panel.png
  Final metric comparison: figures/final_metric_comparison.png
  총 {N}개 Figure 생성

[Phase 4] Interpretation + Writing...
  Executive Summary 생성 완료
  Figure 해석 작성: {N}개
  Proposed Improvements: {N}개
  → Writing Quality Loop:
    Iteration 1: Score 72/100
      - Critical: Definition missing (2)
      - Warning: Figure without interpretation (1)
    Iteration 2: Score 85/100
      All critical issues resolved

[Phase 5] Verification...
  → Numerical: {verified}/{total}
  → Logic: {sound}/{total}
  → Figure consistency: {matched}/{total}
  → Verdict: PASS

[Phase 6] Export...
  LaTeX 변환 완료
  PDF 생성 완료: study.pdf

Complete!
  - New experiments: {experiment_names}
  - Writing quality: {score}/100
  - Figures: {N}개
  - Hypotheses: {N}개
  - Next experiments: {N}개

---

质量标准摘要

标准	权重	说明
定义优先	25 分	100% 定义术语，采用“X is Y”形式
主题优先	20 分	90% 的段落采用总分结构
比较与对照	15 分	必须包含比较表和差异分析
洞察深度	15 分	包含“为什么”的分析和机制假设
尽量少用形容词	5 分	使用基于数值的表达，尽量少用形容词
Figure 质量	10 分	Figure 解读、caption 和引用对应关系
后续步骤清晰度	10 分	与假设关联、明确 config 细节并给出预测

总体通过标准：>= 80 分

---

Additional Resources

• references/interpretation-template.md - 실험 해석 템플릿
• references/quality-criteria.md - 글 품질 평가 상세 기준
• scripts/generate_plots.py - matplotlib 기반 차트 생성 유틸리티
• scripts/export_latex_pdf.py - LaTeX 변환 + Figure 포함 PDF 생성
• scripts/export_pdf.py - PDF 변환 유틸리티 (Fallback)

---

Cautions

1. 로그 파일이 ground truth: 로그에 없는 수치는 사용 불가
2. Append Only: 이전 결과를 절대 수정하지 않음
3. 매 수치에 출처: (source: filepath:L행번호) 필수
4. 가설은 falsifiable: 검증 불가능한 가설은 삭제
5. 최대 3회 반복: Writing Quality Loop + Verification 각각 최대 3회
6. 새 실험 우선: 이미 문서화된 실험은 자동 스킵
7. [NEW] 태그: 새 추가분 명확히 표시
8. Figure 필수: 모든 실험 보고서에 최소 1개 이상의 Figure 포함
9. 코드 스니펫 검증: Implementation/Improvements 코드는 문법 정확성 확인
10. LaTeX 호환성: Markdown 내 특수문자 이스케이프 확인 (_, %, #, & 등)