Update Study – Enhanced Iterative Experiment Analysis

실험 로그를 분석하여 study 문서를 업데이트하는 스킬입니다.

Core Features

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

Usage

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

• log_path(s): 실험 로그 파일 경로 (공백으로 구분하여 여러 개 가능)
• study_md_path: 업데이트할 study markdown 파일 경로

Arguments Parsing

$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"

Workflow Overview

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)
  └── 완료 보고

Phase 0: Incremental Detection (NEW)

Step 0.1: 로그 디렉토리 스캔

1. logs/ 디렉토리에서 모든 로그 파일 목록 생성
   - 패턴: *_train.log, *_eval.log, *.log
   - 파일 수정 시간 기준 정렬

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: 새 실험 결정

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

Phase 1: File Verification

Step 1.1: 파일 확인

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

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

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

Step 1.2: 기존 study.md 분석

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

Phase 2: Interpretation (experiment-interpreter)

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 템플릿을 따라주세요."

Phase 2b: Writing Quality Loop (NEW)

Step 2b.1: Quality Evaluation

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

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

1. Definition-First (30점)
   - 모든 전문 용어가 "X is Y" 형태로 정의되었는가?
   - 새로운 개념이 사용 전에 정의되었는가?

2. Topic-First Paragraphs (25점)
   - 모든 문단이 핵심 결과/주장으로 시작하는가?
   - 첫 문장만 읽어도 문단 내용을 파악할 수 있는가?

3. Compare-Contrast (20점)
   - 새 결과가 이전 실험과 비교되었는가?
   - 차이의 원인/해석이 제시되었는가?

4. Insight Depth (15점)
   - 표면적 기술을 넘어 "왜"에 대한 분석이 있는가?
   - 예상과 다른 결과에 대한 가설이 있는가?

5. Minimal Adjectives (10점)
   - 불필요한 수식어가 없는가?
   - 주관적 표현 대신 구체적 수치가 사용되었는가?

총점: /100
통과 기준: ≥ 80점

Step 2b.2: Revision

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

1. [Critical: Definition Missing]
   - 미정의 용어 목록 작성
   - 각 용어에 대해 "X is Y" 정의 추가

2. [Critical: Topic-Last Paragraph]
   - 문단 재구성: 핵심 → 설명 → 근거 순서로

3. [Warning: No Comparison]
   - 이전 실험과의 비교 테이블 추가
   - 차이 분석 문단 추가

4. [Warning: Shallow Insight]
   - "왜 이런 결과가 나왔는가?" 분석 추가
   - 가설 강화

5. [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: 현재 최선 버전으로 진행 + 이슈 보고

Phase 3: Document Update

추가 규칙

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

[NEW] 태그 처리

---

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

...

다음 /update-study 실행 시:

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

Phase 4: Verification (experiment-verifier)

Task Tool 호출

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

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

  ## 검증 대상 (새로 추가된 섹션)
  {Phase 3에서 추가한 내용}

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

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

  ## 검증 요구사항
  1. 모든 수치를 원본 로그와 대조 (파일:라인 직접 확인)
  2. 해석의 논리적 타당성 검증
  3. 모든 가설의 falsifiability 확인
  4. 다음 실험의 실행 가능성 확인
  5. 기존 결과 변경 여부 확인

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

결과 처리

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

Phase 5: Export (NEW)

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}개

Progress Reporting

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

[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}개

Quality Criteria Summary

Overall Pass: ≥ 80점

Additional Resources

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

Cautions

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