update-study

1. Incremental Detection - 새 실험만 분석 (이미 문서화된 실험 스킵)
2. Iterative Writing Loop - 글 품질 개선 루프 (clarity, coherence, insight depth)
3. Zero Hallucination - 로그 레벨 교차 검증
4. PDF Export - 최종 문서를 PDF로 변환

```

/update-study

```

• log_path(s): 실험 로그 파일 경로 (공백으로 구분하여 여러 개 가능)
• 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"

```

---

```

Phase 0: Incremental Detection (NEW)

├── logs/ 스캔

├── 기존 study 파싱 (이미 분석된 실험 식별)

└── 새 실험 목록 생성 → 없으면 "No new experiments" 출력 후 종료

Phase 1: File Verification

├── 로그 파일 존재 확인

└── study.md 읽기

Phase 2: Interpretation

├── experiment-interpreter 호출

└── 메트릭 추출 + 초안 작성

Phase 2b: Writing Quality Loop (NEW)

├── Quality evaluation (clarity, coherence, insight)

├── Revision if needed (definition-first, topic-first)

└── Max 3 iterations, pass at score ≥ 80

Phase 3: Append to Document

├── [NEW] 태그로 새 섹션 표시

└── Timeline 테이블 업데이트

Phase 4: Verification

├── experiment-verifier 호출

├── 숫자 정확성 검증

└── 논리 일관성 검증

Phase 5: Export (NEW)

├── PDF 변환 (pandoc/weasyprint)

└── 완료 보고

```

---

Step 0.1: 로그 디렉토리 스캔

```

1. logs/ 디렉토리에서 모든 로그 파일 목록 생성

- 패턴: _train.log, _eval.log, *.log

- 파일 수정 시간 기준 정렬

1. 입력된 로그 파일 목록과 교차 확인

```

Step 0.2: 기존 Study 분석

```

기존 study.md에서 이미 문서화된 실험 식별:

1. 실험 헤더 패턴 검색:

- ### E{N}: 또는 ### Experiment:

- ## Experiment {N}:

1. 로그 파일 참조 추출:

- [_train.log:] 형식의 출처 표기

- Source: 열의 파일명

1. 문서화된 실험 목록 구축:

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}")

```

---

Step 1.1: 파일 확인

```

1. 새 실험 로그 파일 존재 확인

- 각 log_path에 대해 파일 존재 여부 확인

- 존재하지 않으면 에러 메시지 출력 후 중단

1. study.md 파일 확인

- 파일이 존재하면 Read tool로 전체 내용 읽기

- 파일이 없으면 새로 생성할 것임을 안내

1. 로그 파일 요약 정보 추출 (빠른 스캔)

- 실험 config 파일 경로

- 실험 모드 (train/evaluate)

- 최종 metric 라인 위치

```

Step 1.2: 기존 study.md 분석

```

기존 study.md에서 확인할 사항:

• 이미 기록된 실험 목록
• 비교 가능한 baseline 결과
• 미해결 가설 목록
• 계획된 실험 목록 (이번 실험이 기존 계획에 해당하는지)

```

---

Task Tool 호출

```

Task tool 사용:

• subagent_type: "experiment-interpreter"
• prompt:

"다음 실험 로그를 분석하고 study.md 업데이트 초안을 생성해주세요.

## 로그 파일

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

## 기존 study.md 내용 (비교용)

{기존 study.md의 결과 요약 테이블}

## 이전 검증 피드백 (있는 경우)

{verifier의 feedback_summary - 첫 iteration에는 없음}

## 요구사항

1. 로그에서 모든 수치를 추출하고 (source: filepath:L행번호) 형식으로 출처 표기

2. 기존 결과와 비교 테이블 생성

3. 데이터에 기반한 해석 작성

4. 각 가설은 falsifiable + prediction + falsification 포함

5. 다음 실험은 구체적 config 변경 포함

6. 출력은 study.md에 바로 append할 수 있는 markdown 형식

## 출력 형식

references/interpretation-template.md 템플릿을 따라주세요."

```

---

Step 2b.1: Quality Evaluation

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

```

평가 기준 (references/quality-criteria.md 참조):

1. Definition-First (30점)

- 모든 전문 용어가 "X is Y" 형태로 정의되었는가?

- 새로운 개념이 사용 전에 정의되었는가?

1. Topic-First Paragraphs (25점)

- 모든 문단이 핵심 결과/주장으로 시작하는가?

- 첫 문장만 읽어도 문단 내용을 파악할 수 있는가?

1. Compare-Contrast (20점)

- 새 결과가 이전 실험과 비교되었는가?

- 차이의 원인/해석이 제시되었는가?

1. Insight Depth (15점)

- 표면적 기술을 넘어 "왜"에 대한 분석이 있는가?

- 예상과 다른 결과에 대한 가설이 있는가?

1. Minimal Adjectives (10점)

- 불필요한 수식어가 없는가?

- 주관적 표현 대신 구체적 수치가 사용되었는가?

총점: /100

통과 기준: ≥ 80점

```

Step 2b.2: Revision

점수가 80점 미만인 경우 수정:

```

1. [Critical: Definition Missing]

- 미정의 용어 목록 작성

- 각 용어에 대해 "X is Y" 정의 추가

1. [Critical: Topic-Last Paragraph]

- 문단 재구성: 핵심 → 설명 → 근거 순서로

1. [Warning: No Comparison]

- 이전 실험과의 비교 테이블 추가

- 차이 분석 문단 추가

1. [Warning: Shallow Insight]

- "왜 이런 결과가 나왔는가?" 분석 추가

- 가설 강화

1. [Minor: Excessive Adjectives]

- "significantly improved" → "+12.5%p"

- "much faster" → "2.3x speedup"

```

Step 2b.3: Iteration Control

```

최대 반복: 3회

Iteration 1: 초안 → 품질 평가 → 수정 (필요시)

→ Score ≥ 80: Phase 3으로 진행

→ Score < 80: feedback 수집

Iteration 2: 수정안 → 재평가

→ Score ≥ 80: Phase 3으로 진행

→ Score < 80: feedback 수집

Iteration 3: 최종 수정 → 재평가

→ Score ≥ 80: Phase 3으로 진행

→ Score < 80: 현재 최선 버전으로 진행 + 이슈 보고

```

---

추가 규칙

1. Append Only: 기존 내용 뒤에 새 섹션 추가. 기존 내용 수정 금지.
2. [NEW] 태그: 새로 추가된 실험에 [NEW] 태그 표시 (다음 업데이트 시 제거)
3. 구분선: 새 실험 전에 --- 구분선 삽입
4. 날짜 표기: 실험 실행 날짜 (로그 타임스탬프 기반)
5. 일관된 포맷: references/interpretation-template.md 템플릿 준수

[NEW] 태그 처리

```markdown

---

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

...

```

다음 /update-study 실행 시:

1. 이전에 추가된 [NEW] 태그 모두 제거
2. 새로 추가되는 섹션에만 [NEW] 태그 부여

---

Task Tool 호출

```

Task tool 사용:

• subagent_type: "experiment-verifier"
• prompt:

"다음 study.md 업데이트 내용을 검증해주세요.

## 검증 대상 (새로 추가된 섹션)

{Phase 3에서 추가한 내용}

## 원본 로그 파일 경로

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

## 기존 study.md (변경 여부 확인용)

{기존 study.md 내용}

## 검증 요구사항

1. 모든 수치를 원본 로그와 대조 (파일:라인 직접 확인)

2. 해석의 논리적 타당성 검증

3. 모든 가설의 falsifiability 확인

4. 다음 실험의 실행 가능성 확인

5. 기존 결과 변경 여부 확인

## 출력

JSON 형식의 검증 보고서를 반환해주세요."

```

결과 처리

```python

if verdict == "PASS":

# Phase 5로 진행

elif iteration < 3:

# feedback_summary를 Phase 2로 전달

# interpreter에게 수정 요청

else:

# 최대 반복 도달

# 현재 최선 버전 저장

# 미해결 이슈 사용자에게 보고

```

---

Step 5.1: Markdown 확정

```

1. study.md 최종 내용 저장
2. [NEW] 태그가 포함된 섹션 확인

```

Step 5.2: PDF 변환

```

scripts/export_pdf.py 사용:

python scripts/export_pdf.py study.md study.pdf

변환 옵션:

• TOC (Table of Contents) 포함
• [NEW] 태그 시각적 강조 (노란색 하이라이트)
• 테이블 깔끔한 포맷팅
• 코드 블록 문법 강조

Fallback 순서:

1. pandoc + LaTeX (최상의 품질)
2. weasyprint (pandoc 없을 시)
3. Markdown만 저장 (PDF 변환 실패 시 경고)

```

Step 5.3: 완료 보고

```

✅ Update Complete!

📄 Markdown: study.md

📑 PDF: study.pdf (optional)

📊 New experiments: {N}개

🔬 Hypotheses: {N}개

🧪 Next experiments: {N}개

```

---

실행 중 사용자에게 상태를 보고합니다:

```

[Phase 0] Incremental Detection...

✓ Scanned logs/: {N}개 파일

✓ Already documented: {M}개 실험

✓ New experiments: {K}개 발견

[Phase 1] File Verification...

✓ 로그 파일 확인: {K}개

✓ study.md 읽기 완료

[Phase 2] Interpretation...

✓ 수치 추출: {N}개 메트릭

✓ 비교 테이블 생성

[Phase 2b] Writing Quality Loop...

→ Iteration 1: Score 72/100

- Critical: Definition missing (2)

- Warning: Topic-last paragraph (1)

→ Iteration 2: Score 85/100

✓ All critical issues resolved

[Phase 3] Document Update...

✓ 새 섹션 추가 ([NEW] 태그)

[Phase 4] Verification...

→ Numerical: {verified}/{total}

→ Logic: {sound}/{total}

→ Verdict: PASS

[Phase 5] Export...

✓ PDF 변환 완료

✅ Complete!

- New experiments: {experiment_names}

- Accuracy: {X.XX%}

- Hypotheses: {N}개

- Next experiments: {N}개

```

---

| Criterion | Weight | Pass Threshold |

|-----------|--------|----------------|

| Definition-First | 30점 | 용어 100% 정의 |

| Topic-First | 25점 | 문단 90% 두괄식 |

| Compare-Contrast | 20점 | 비교 테이블 필수 |

| Insight Depth | 15점 | "왜" 분석 포함 |

| Minimal Adjectives | 10점 | 수치 기반 표현 |

Overall Pass: ≥ 80점

---

• references/interpretation-template.md - 실험 해석 템플릿
• references/quality-criteria.md - 글 품질 평가 상세 기준
• scripts/export_pdf.py - PDF 변환 유틸리티

---

1. 로그 파일이 ground truth: 로그에 없는 수치는 사용 불가
2. Append Only: 이전 결과를 절대 수정하지 않음
3. 매 수치에 출처: (source: filepath:L행번호) 필수
4. 가설은 falsifiable: 검증 불가능한 가설은 삭제
5. 최대 3회 반복: 무한 루프 방지
6. 새 실험 우선: 이미 문서화된 실험은 자동 스킵
7. [NEW] 태그: 새 추가분 명확히 표시