eval-summary by team-attention

---
name: eval-summary
description: |
  readings.ts의 요약 필드가 원본 kr 마크다운과 비교하여 잘 작성되었는지 평가합니다.
  이슈별로 개선사항을 제안하고 사용자 컨펌 후 readings.ts를 수정합니다.
  사용: /eval-summary week1 또는 /eval-summary week1/slug
arguments:
  - name: path
    description: |
      week{N} 또는 week{N}/slug 형식
      - 주차 전체: week1 (해당 주차의 요약 필드가 있는 모든 리딩 검증)
      - 개별 리딩: week1/deep-dive-llms
    required: true
  - name: skip-apply
    description: 수정 적용 없이 리포트만 생성
    required: false
  - name: auto-apply
    description: 사용자 확인 없이 모든 수정 자동 적용
    required: false
---

# eval-summary Skill

readings.ts의 요약 필드를 원본 kr 마크다운과 비교하여 품질을 평가합니다.

## 사용법

```bash
# 주차 전체 검증
/eval-summary week1

# 개별 리딩 검증
/eval-summary week1/deep-dive-llms
/eval-summary week1/how-openai-uses-codex

# 옵션
/eval-summary week1 --skip-apply    # 리포트만 생성
/eval-summary week1 --auto-apply    # 자동 적용
```

## 검증 대상 필드

| 필드 | 설명 | 타입 |
|------|------|------|
| `tldr` | TL;DR 전체 요약 | string |
| `learningGoals` | 학습 목표 배열 | string[] |
| `chapterSummaries` | 챕터별 요약 | ChapterSummary[] |
| `motivation` | 동기부여 섹션 | object |
| `keyTakeaways` | 핵심 요점 | object[] |

## 검증 기준

| 기준 | 설명 |
|------|------|
| 정확성 | 원문 내용을 정확히 반영하는가 |
| 완전성 | 중요한 내용이 누락되지 않았는가 |
| 간결성 | 불필요하게 길거나 중복되지 않았는가 |
| 일관성 | 용어와 어조가 일관되는가 |

## 입출력

### 입력 파일

| 소스 | 경로 |
|------|------|
| readings.ts | `src/content/readings.ts` |
| kr 마크다운 (기본) | `docs/week{N}/{slug}/kr/index.md` |
| kr 마크다운 (부모) | `docs/week{N}/{slug}/kr/_index.md` |

### 출력 파일

```
.claude/outputs/eval-summary/
└── week{N}/{slug}/
    └── evaluation-report.json
```

## 워크플로우

```
/eval-summary week1/slug
        │
        ▼
┌─────────────────────────────────┐
│ 1. 경로 파싱                     │
│    week{N} → 주차 전체          │
│    week{N}/slug → 개별 리딩     │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ 2. 데이터 로드                   │
│    - readings.ts 요약 필드      │
│    - kr 마크다운 파일           │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ 3. Task: summary-evaluator      │
│    요약 vs 원본 비교 검증       │
│    → JSON 이슈 리포트           │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ 4. 이슈별 사용자 컨펌           │
│    (--skip-apply가 아닌 경우)   │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ 5. 승인된 수정사항 적용         │
│    Edit tool로 readings.ts     │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ 6. 결과 요약 출력               │
└─────────────────────────────────┘
```

## 실행 지침

이 스킬이 호출되면 다음 단계를 따르세요.

### Step 1: 경로 파싱 및 대상 리딩 수집

```
경로 구조 확인:
- 1단계 (week1): 주차 전체 검증
  → readings.ts에서 week === 1인 모든 리딩 추출
  → 요약 필드(tldr, learningGoals, chapterSummaries, motivation, keyTakeaways)가
    하나 이상 있는 리딩만 필터링
- 2단계 (week1/slug): 개별 리딩 검증
  → readings['week1/slug'] 추출

대상 리딩 수집 로직 (주차 전체 시):
1. Read tool로 src/content/readings.ts 파일 읽기
2. 해당 주차의 모든 리딩 키 추출
3. 요약 필드가 있는 리딩만 필터링
4. 각 리딩에 대해 검증 수행
```

### Step 2: 데이터 로드

```
각 리딩에 대해:

1. readings.ts에서 요약 필드 추출:
   - tldr (YouTube 콘텐츠)
   - learningGoals (YouTube 콘텐츠)
   - chapterSummaries (YouTube 콘텐츠)
   - motivation (동기부여 섹션)
   - keyTakeaways (핵심 요점)

2. kr 마크다운 파일 경로 결정:
   - isParent === true && children 있음:
     → docs/week{N}/{slug}/kr/_index.md
   - 그 외:
     → docs/week{N}/{slug}/kr/index.md

3. Read tool로 kr 마크다운 파일 읽기

파일이 없는 경우:
- kr 마크다운 없음: "번역 파일을 찾을 수 없습니다: /translate-reading 먼저 실행해주세요."
- 요약 필드 없음: "검증할 요약 필드가 없습니다." (해당 리딩 스킵)
```

### Step 3: summary-evaluator 에이전트 호출

```
Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/eval-summary/summary-evaluator.md 내용
         + "## 입력 데이터"
         + "### 리딩 키: {week/slug}"
         + "### readings.ts 요약 필드:"
         + [tldr, learningGoals, chapterSummaries, motivation, keyTakeaways를 JSON으로]
         + "### 원본 kr 마크다운:"
         + [마크다운 전체 내용]
- description: "summary-evaluator - {slug} 요약 품질 검증"

에이전트가 JSON 형식으로 이슈 리포트를 반환합니다.
JSON 블록(```json ... ```) 추출하여 파싱합니다.
```

### Step 4: 리포트 저장

```
출력 디렉토리 생성:
mkdir -p .claude/outputs/eval-summary/week{N}/{slug}/

결과 저장:
Write tool로 evaluation-report.json 저장

--skip-apply 옵션인 경우:
→ 리포트 내용 출력 후 종료
→ Step 5, 6 스킵
```

### Step 5: 이슈별 사용자 컨펌 (--skip-apply가 아닌 경우)

```
이슈를 severity 순서로 정렬: critical → major → minor

각 이슈에 대해:

--auto-apply 옵션인 경우:
→ 모든 이슈 자동 승인

그 외:
→ AskUserQuestion tool 사용

AskUserQuestion 호출 예시:
questions:
  - question: "이 수정사항을 적용하시겠습니까?"
    header: "[Major] {field}"
    options:
      - label: "적용"
        description: |
          현재: "{current}"
          수정: "{suggested}"
          이유: {reason}
      - label: "건너뛰기"
        description: "이 이슈를 무시하고 다음으로 진행"
    multiSelect: false

사용자 선택 처리:
- "적용": approvedIssues 배열에 추가
- "건너뛰기": skippedIssues 배열에 추가
- "Other" (직접 입력): customFixes 배열에 추가 (사용자 입력값 사용)
```

### Step 6: 승인된 수정사항 적용

```
approvedIssues와 customFixes의 각 항목에 대해:

1. Read tool로 src/content/readings.ts 파일 읽기
2. 해당 리딩 키 위치 찾기: 'week{N}/{slug}':
3. 수정할 필드 위치 찾기
4. Edit tool로 수정 적용:
   - old_string: 현재 값
   - new_string: suggested 또는 custom 값

필드별 수정 방법:
- tldr: tldr: '...' 라인 찾아서 교체
- learningGoals: learningGoals: [...] 블록 찾아서 교체
- chapterSummaries: chapterSummaries 배열 내 특정 항목 교체
- motivation: motivation: {...} 블록 찾아서 교체
- keyTakeaways: keyTakeaways 배열 내 특정 항목 교체

주의: 한글 포함 시 Edit tool 사용 (Write 대신)
     → 정확한 old_string 매칭 필요
```

### Step 7: 결과 요약 출력

```
완료 메시지 형식:

✅ 요약 평가 완료!

📊 **검증 결과**
- 검증된 리딩: {N}개
- 발견된 이슈: {N}건
  - Critical: {N}건
  - Major: {N}건
  - Minor: {N}건

📝 **적용된 수정** (--skip-apply가 아닌 경우)
- 승인됨: {N}건
- 건너뜀: {N}건

📁 **리포트 저장 위치**
.claude/outputs/eval-summary/week{N}/{slug}/evaluation-report.json

💡 **다음 단계**
pnpm build  # TypeScript 검증
pnpm dev    # 웹에서 확인
```

## 옵션

### --skip-apply

수정 적용 없이 리포트만 생성합니다.
- 이슈 발견 후 사용자 컨펌 과정 스킵
- 리포트 파일만 저장하고 종료

### --auto-apply

사용자 확인 없이 모든 수정을 자동 적용합니다.
- 발견된 모든 이슈의 suggested 값을 자동 적용
- 주의: 검토 없이 적용되므로 사용 시 주의 필요

## Agent 파일

- `.claude/agents/eval-summary/summary-evaluator.md` - 요약 품질 평가 에이전트

## 이슈 유형

| 유형 | 설명 |
|------|------|
| `inaccuracy` | 원문과 다른 내용 |
| `omission` | 중요 내용 누락 |
| `redundancy` | 불필요한 반복 |
| `inconsistency` | 용어/스타일 불일치 |
| `verbosity` | 불필요하게 긴 표현 |

## 심각도

| 레벨 | 기준 |
|------|------|
| `critical` | 핵심 내용 오류, 심각한 누락 |
| `major` | 중요 정보 누락/왜곡 |
| `minor` | 표현 개선, 일관성 문제 |

## 에러 처리

| 상황 | 처리 |
|------|------|
| kr 마크다운 없음 | "번역 파일을 찾을 수 없습니다: /translate-reading 먼저 실행해주세요." |
| readings.ts에 리딩 없음 | "리딩을 찾을 수 없습니다: /upload-reading 먼저 실행해주세요." |
| 요약 필드 없음 | "검증할 요약 필드가 없습니다." (해당 리딩 스킵) |
| JSON 파싱 실패 | 원본 출력 저장 후 수동 검토 안내 |

## 점수 기준

| 점수 | 의미 |
|------|------|
| 9-10 | 우수, 수정 불필요 |
| 7-8 | 양호, Minor 수정 권장 |
| 5-6 | 보통, Major 수정 필요 |
| 3-4 | 미흡, 상당 부분 재작성 권장 |
| 1-2 | 불량, 전체 재작성 필요 |