weekly-report-writer

Generate comprehensive weekly research reports by:

1. Analyzing Git repository changes from the past week
2. Building a Fact Base of verified information
3. Planning document structure with report-planner agent
4. Writing structured reports following strict academic writing principles
5. Iteratively improving quality with report-reviewer agent
6. Saving reports to the project root as WEEKLY_REPORT_YYYYMMDD.md

---

```

Phase 1: Information Gathering + Fact Base

↓

Phase 2: Document Structure Planning (report-planner agent)

↓

Phase 3: Draft Writing (Blueprint-based)

↓

Phase 4: Iterative Improvement Loop

┌─────────────────────────────────────┐

│ report-reviewer → Fact Checker │

│ ↓ │

│ Issues Found? ──Yes──→ Rewrite │

│ │ │ │

│ No └──→──┤

│ ↓ │

│ Complete! │

└─────────────────────────────────────┘

```

---

Step 1.1: Git Analysis

```bash

# Check current status

git status

# If uncommitted changes exist, offer to commit them first

# Get commits from past week

git log --since="1 week ago" --oneline --all

git log --since="1 week ago" --stat --all

# Get detailed diff

git diff HEAD~10..HEAD --stat

```

Step 1.2: File Change Analysis

Categorize changes by type:

• Experiment Results: New JSON/CSV files in results/ or outputs/ directories
• Analysis Scripts: Modified Python files in analysis/, src/, or root directories
• Visualizations: New PNG/PDF files in figures/ or writing/ directories
• Documentation: Modified .tex, .md, or similar files
• Configuration: Updates to YAML, JSON config files

Step 1.3: Build Fact Base

For each significant change, extract and verify facts:

1. Read code files to understand what was implemented
2. Check CLAUDE.md, README.md for documented context
3. Verify paper citations using WebSearch if needed
4. Record verified facts with sources

Fact Base Structure (internal tracking):

```

Verified Facts:

• Claim: "LTPO 학습률은 0.03이다"

Source: ltpo/memgen_ltpo.py

Verified: ✓

• Claim: "Titans 논문은 2025년 발표"

Source: WebSearch - arXiv:2501.00663

Verified: ✓

Unverified Claims:

• "MemGen 논문 저자" - WebSearch 필요

```

---

Invoke report-planner Agent

Use the Task tool to invoke the report-planner agent:

```

Task: report-planner

Prompt: Based on the following information gathered from Git analysis, create a document Blueprint for the weekly report.

[Include summary of changes, technical terms identified, concepts that need explanation]

```

Receive Blueprint

The report-planner agent will return:

1. Document structure with section core messages
2. Definition list (terms needing "X는 Y이다" definitions)
3. Compare-contrast list (concept pairs to compare)
4. Paragraph flow with 두괄식 first sentences

---

Write Following Blueprint Structure

1. Follow the section order from Blueprint
2. Include all term definitions at first use
3. Apply compare-contrast for identified concept pairs
4. Use 두괄식 first sentences from Blueprint
5. Connect paragraphs with planned connectives

Report Structure

```markdown

# 주간 연구 보고서 (YYYY-MM-DD)

[One comprehensive paragraph summarizing ALL changes. Start with the most significant achievement. Define key terms immediately. Connect related work logically.]

[Category 1 Name]

[Paragraph starting with main accomplishment. Define technical terms. Compare with previous approaches. Explain significance.]

[Category 2 Name]

[Continue for each category. Use connective words for flow between sections.]

[If ongoing tasks exist, describe in prose. Otherwise state: "현재 진행 중인 작업은 없다."]

[Optional section. Only include if discussed with user.]

```

---

Step 4.1: Quality Evaluation

Invoke report-reviewer agent:

```

Task: report-reviewer

Prompt: Evaluate this weekly report draft for quality and understandability.

[Include the draft report]

```

Step 4.2: Fact Checking (Hallucination Prevention) - CRITICAL

⚠️ HARD CONSTRAINT: Hallucination은 단 하나도 허용하지 않는다.

모든 사실적 주장은 반드시 검증해야 하며, 검증되지 않은 정보는 보고서에 포함할 수 없다.

#### 4.2.1: Hallucination 유형별 검증 방법

| Hallucination 유형 | 검증 방법 | 도구 |

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

| 존재하지 않는 기능 | 해당 코드 파일에서 기능 구현 여부 확인 | Read tool |

| 잘못된 수치/파라미터 | config 파일, 코드, 결과 파일과 대조 | Read tool |

| 허위 논문 인용 | 논문 존재 여부 및 내용 검증 | WebSearch |

| 잘못된 저자/연도 | 실제 논문 메타데이터 확인 | WebSearch |

| 과장된 성능 주장 | 실험 결과 파일과 직접 대조 | Read tool |

| 존재하지 않는 API/함수 | 공식 문서 또는 코드베이스 확인 | WebSearch, Read |

#### 4.2.2: 검증 프로세스

```

보고서의 모든 문장 순회:

│

├─ [기술적 주장] → 코드 파일에서 직접 확인

│ 예: "LTPO 학습률은 0.03이다"

│ 검증: ltpo/config.yaml 또는 해당 .py 파일 읽기

│

├─ [수치 데이터] → 원본 데이터와 대조

│ 예: "실험 결과 87% 정확도 달성"

│ 검증: results/*.json 파일에서 실제 값 확인

│

├─ [논문 인용] → WebSearch로 검증

│ 예: "Zhang et al. (2024)에 따르면..."

│ 검증: 논문 존재 여부, 저자, 연도, 내용 일치 확인

│

├─ [구현 내용] → Git diff 및 코드 확인

│ 예: "새로운 reward 함수를 추가했다"

│ 검증: git log, 해당 파일에서 함수 존재 확인

│

└─ [설정값] → config 파일 확인

예: "batch size 32로 학습"

검증: configs/*.yaml 파일에서 확인

```

#### 4.2.3: Fact Base 업데이트

검증 결과를 Fact Base에 기록:

```

✓ Verified:

• "LTPO lr=0.03" (ltpo/memgen_ltpo.py:36)
• "Titans 논문 2025년" (WebSearch: arXiv:2501.00663)
• "GPT 파산율 4.6%" (results/gpt_corrected.json:bankruptcy_rate)

✗ HALLUCINATION DETECTED:

• "99% 정확도 달성" → 실제: 87% (results/exp1.json)
• "Kim et al. (2024)" → WebSearch: 해당 논문 없음
• "자동 저장 기능" → 코드에 해당 기능 없음

⚠️ Needs Verification:

• "MemGen은 2024년 발표" → WebSearch 필요

```

#### 4.2.4: Hallucination 발견 시 조치

1. 즉시 해당 내용 삭제 또는 수정
2. 올바른 정보로 대체 (검증된 사실만 사용)
3. 검증 불가능한 내용은 보고서에서 제외
4. 재검증 후 다음 iteration 진행

절대 금지 사항:

• 검증 없이 수치 언급 ❌
• 읽지 않은 논문 인용 ❌
• 확인하지 않은 코드 기능 설명 ❌
• 추측성 내용을 사실처럼 서술 ❌

Step 4.3: Check Termination Conditions

Success Criteria (all must be met):

• Critical issues: 0
• Hallucinations: 0
• Overall score: >= 80

If criteria met: Save final report and complete

If criteria not met: Proceed to rewriting

Step 4.4: Rewriting Based on Feedback

Address each issue:

1. Add missing definitions for undefined terms
2. Add compare-contrast for unexplained new approaches
3. Improve paragraph flow with connective words
4. Fix any factual errors identified by fact checker
5. Simplify complex sections for better understandability

Step 4.5: Loop Control

• Maximum iterations: 5
• If max iterations reached without meeting criteria:

- Save best version so far

- Report unresolved issues to user

- Request manual intervention

---

1. 정의 우선 (Definition First)

모든 전문 용어는 "X는 Y이다" 형태로 먼저 정의한다.

• 용어가 처음 등장할 때 즉시 정의
• 정의는 다른 미정의 용어를 사용하지 않음
• 독자가 해당 분야 전문가가 아니라고 가정

예시:

• ✅ "LTPO(Latent Thought Policy Optimization)는 inference 시점에서 모델 가중치를 변경하지 않고 latent 표현만 최적화하는 기법이다."
• ❌ "LTPO를 적용하여 성능을 개선했다." (정의 없이 사용)

2. 비교-대조 설명 (Compare-Contrast)

새로운 접근법은 기존 방식과 비교하여 설명한다.

형식: "기존의 A가 [특징]... 반면, B는 [다른 특징]..."

예시:

• ✅ "기존의 RAG가 외부 데이터베이스를 검색하여 정보를 가져오는 반면, MemGen은 모델 내부에서 압축된 메모리를 생성하여 추론에 활용한다."
• ❌ "MemGen을 사용하여 메모리를 생성했다." (비교 없이 설명)

3. 초심자 이해도 (Beginner Understandability)

배경지식 없는 독자도 글을 이해할 수 있어야 한다.

• "무엇을" → "왜" → "어떻게" 순서로 설명
• 복잡한 개념은 점진적으로 구축 (쉬운 것 → 어려운 것)
• 모든 전문 용어가 정의되기 전에 사용되지 않음

4. 두괄식 (Topic-First Structure)

모든 문단은 핵심 주장이나 결론으로 시작한다.

각 문단의 첫 문장을 읽는 것만으로 전체 내용을 파악할 수 있어야 한다.

5. 문단/문장 연결의 유기성 (Coherent Flow)

문단 간, 문장 간 논리적 흐름이 자연스러워야 한다.

• 문단 간: 앞 문단의 결론이 뒷 문단의 전제가 되도록
• 문장 간: 각 문장이 앞 문장의 내용을 발전시키거나 구체화하도록
• 접속어 활용: "이를 위해", "그 결과", "한편", "이에 따라" 등

6. 줄글 형태 (Prose Format)

*보고서 본문에서 bullet point (-, , •)를 사용하지 않는다.**

예외: 코드 블록 또는 파일 목록 표시 시에만 허용

7. 추상적 서술 (Abstract-Level Writing)

연구의 목표, 접근법, 의의를 추상적 수준에서 서술한다.

금지 사항:

• 파일 경로 (예: /home/ubuntu/project/src/model.py)
• 함수명, 클래스명, 변수명 (예: _calculate_rewards())
• 코드 줄 수 (예: "950줄의 코드를 추가")

권장 사항:

• "무엇을 왜 했는지"를 개념적으로 설명
• 연구 목표와 해결하려는 문제 중심
• 방법론의 핵심 아이디어 설명

8. 수식어 최소화 (Minimal Adjectives)

불필요한 수식어를 제거하고, 필요시 구체적 수치를 사용한다.

금지어: 매우, 상당히, 아주, 굉장히, 크게, 작게 (수치 없이 단독 사용)

---

Before each iteration, verify:

| Category | Criterion | Check |

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

| 정의 | 모든 전문 용어가 "X는 Y이다" 형태로 정의되었는가? | □ |

| 비교-대조 | 새로운 접근법이 기존 방식과 비교되었는가? | □ |

| 초심자 이해도 | 배경지식 없이도 이해 가능한가? | □ |

| 두괄식 | 모든 문단이 핵심 주장으로 시작하는가? | □ |

| 흐름 | 문단 간, 문장 간 연결이 자연스러운가? | □ |

| 줄글 | 본문에 bullet point가 없는가? | □ |

| 추상성 | 파일 경로, 함수명이 없는가? | □ |

| 사실 검증 | 모든 주장이 출처와 일치하는가? | □ |

---

Save the generated report to the project root:

```

./WEEKLY_REPORT_YYYYMMDD.md

```

Where YYYYMMDD is the current date (e.g., WEEKLY_REPORT_20260105.md).

---

During execution, report progress to user:

```

[Phase 1] 정보 수집...

✓ Git 커밋 분석 완료 (N건)

✓ 코드 파일 확인 완료

✓ Fact base 구축 완료 (N건)

[Phase 2] 글 구조 계획 (report-planner)...

✓ 문서 Blueprint 생성

✓ 정의 필요 용어: N개

✓ 비교-대조 대상: N쌍

[Phase 3] 초안 작성...

✓ Blueprint 기반 줄글 작성

✓ WEEKLY_REPORT_draft.md 생성

[Phase 4-1] 품질 평가 (report-reviewer)...

→ Critical: N건

→ Warning: N건

→ Score: XX/100

[Phase 4-1] Fact Checking...

→ 검증 완료: N/M

[Phase 4-2] 재작성...

[If needed]

[Phase 4-3] 재평가...

→ Critical: 0건

→ Score: XX/100

✅ 완료! WEEKLY_REPORT_YYYYMMDD.md 저장

```

---

• Git-based: Always analyze Git history, not just current files
• Fact-verified: Never include unverified claims
• Iterative: Quality improves through reviewer feedback loop
• Understandable: Write for readers without background knowledge
• Commit offer: If uncommitted changes exist, offer to commit before report generation
• Language: Default to Korean, but adapt to user's language preference