# LLM Summarizer + Docs Updater 설계

## 1. 개요

Structured Diff JSON과 Breaking Change 판단 결과를 입력받아 자연어 업그레이드 주의사항 문서를 생성하고,
해당 차트 버전의 `CUSTOM-README.md`에 반영한다.

> LLM의 유일한 역할: Structured JSON → Markdown 문서 변환. Diff 생성이나 Breaking 판단은 수행하지 않는다.

---

## 2. LLM Summarizer

### 2.0 실행 조건
- `generate_upgrade_doc`은 **항상 실행**한다 (breaking 여부 무관).
- `breaking=true` → LLM을 사용하여 `custom-values.yaml` 수정 방법을 포함한 상세 가이드 생성.
- `breaking=false` → 템플릿 기반 간단 요약 생성 (LLM 미호출).

> 카탈로그는 신규 배포를 위한 차트 보관소이므로, breaking 여부와 무관하게 모든 업그레이드에 주의사항 기록이 필요하다.

### 2.1 입력

```json
{
  "chart": "airflow",
  "from_version": "1.2.3",
  "to_version": "1.3.0",
  "values": { ... },
  "templates": { ... },
  "crd": { ... },
  "dependencies": { ... },
  "breaking": true,
  "severity": "high",
  "breaking_reasons": [
    {
      "type": "values_key_removed",
      "key": "ingress.enabled",
      "detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — 수정 필요"
    }
  ],
  "warnings": [
    {
      "type": "service_port_changed",
      "resource": "Service/airflow-webserver",
      "detail": "port changed from 8080 to 8081"
    }
  ],
  "docs_context": {
    "CUSTOM-README.md": "..."
  }
}
```

> dip-catalog 구조에서는 버전 디렉토리 내 `CUSTOM-README.md` 내용을 `docs_context`로 제공한다.

### 2.2 Prompt 설계

```
당신은 Kubernetes Helm 업그레이드 주의사항 문서를 작성하는 전문가입니다.

두 Helm 차트 버전 간 변경점을 담은 Structured Diff JSON이 제공됩니다.
이 카탈로그는 신규 배포를 위한 것이며, custom-values.yaml 수정 필요 여부가 핵심입니다.

## 작업
1. 핵심 변경 사항을 평문으로 요약합니다.
2. custom-values.yaml 수정이 필요한 항목(breaking_reasons)을 상세히 설명합니다.
3. 신규 배포 시 참고할 주의사항(warnings)을 기록합니다.
4. 아래 형식의 간결한 Markdown 문서를 생성합니다.

## 규칙
- 입력 JSON에 없는 내용은 절대 추가하지 마세요.
- 추측하지 마세요.
- docs_context는 보조 설명에만 사용하고, diff에 없는 변경을 추가하지 마세요.
- errors가 있으면 분석이 불완전할 수 있음을 명시하세요.
- 배포 담당자가 바로 참고할 수 있도록 명확하게 작성하세요.

## 출력 형식
아래 Markdown 구조를 정확히 지키세요 (`## {to_version}` 헤더는 포함하지 마세요 — `update_docs_file`이 관리):

### 변경 요약
- from_version: <from_version>
- to_version: <to_version>
- <핵심 변경 사항 bullet points>

### custom-values.yaml 수정 필요 항목
<breaking=true면 항목별 수정 방법>
<breaking=false면 "없음">

### 배포 시 주의사항
<warnings가 있으면 나열>
<없으면 섹션 생략>

### 참고
- severity: <severity>
- breaking: <true/false>

---

Input:
<Structured Diff JSON>
```

### 2.3 토큰 예산 관리

대형 chart(airflow, kafka 등)는 Structured Diff JSON이 매우 클 수 있다.

| 전략 | 설명 |
|------|------|
| 중요도 기반 필터링 | breaking_reasons와 changed 항목만 포함, unchanged는 제외 |
| template diff 요약 | 리소스별 상세 diff 대신 `변경된 리소스 목록`만 전달 |
| 청크 분할 | values / templates / crd를 각각 별도 LLM 호출 후 결과 합산 |
| 토큰 상한 설정 | 입력 JSON 최대 크기 제한 (예: 50,000 tokens), 초과 시 요약 버전 사용 |

### 2.4 출력 검증

- **금지 규칙**: 입력 JSON에 없는 버전/리소스를 언급하면 실패 처리.
- **서식 검증**: Markdown 구조가 규정과 다르면 1회 재생성, 실패 시 fallback 템플릿으로 대체.
- **요약 품질 기준**: breaking_reasons 누락/허위 서술은 오류로 간주.

### 2.5 예상 출력 (breaking=true)

> `update_docs_file`이 `## {to_version}` 헤더를 추가하므로, LLM 출력은 `###` 수준부터 시작한다.

```markdown
### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Image tag 1.2.3 → 1.3.0 업데이트
- CPU limit 기본값 추가 (all containers)
- 새 환경변수 `AIRFLOW__CORE__NEW_SETTING` 추가 (scheduler)

### custom-values.yaml 수정 필요 항목
- **`ingress.enabled` 키 삭제**: 차트에서 해당 key가 제거되었습니다.
  현재 custom-values.yaml에서 `ingress.enabled: true`로 설정하고 있는 경우,
  신규 방식(`ingress.create: true` 등)으로 수정이 필요합니다.

### 배포 시 주의사항
- **Service port 변경**: `airflow-webserver` port 8080 → 8081.
  Ingress, load balancer 설정 확인 필요.

### 참고
- severity: high
- breaking: true
```

### 2.6 예상 출력 (breaking=false)

> 템플릿 기반 fallback 출력 (LLM 미호출).

```markdown
### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Chart airflow 1.2.3 → 1.3.0 업데이트
- Values: +2 추가 / -0 삭제 / ~3 변경
- Templates: +0 추가 / -0 삭제

### custom-values.yaml 수정 필요 항목
없음

### 참고
- severity: warning
- breaking: false
```

---

## 3. Docs Updater 설계

### 3.1 역할

생성한 업그레이드 주의사항 Markdown을 해당 차트 버전의 `CUSTOM-README.md`에 반영한다.
(`CUSTOM-README.md`는 배포에 관한 내용을 포함하는 문서로, 업그레이드 주의사항의 적합한 위치다.)

### 3.2 처리 방식

```
1. diff/breaking 결과로 업그레이드 주의사항 생성 (breaking=true면 LLM, 아니면 템플릿)
2. manifests/helm/<chart>/<to_version>/CUSTOM-README.md에 반영
   - "# Upgrade History" 섹션이 없으면 파일 끝에 추가
   - 해당 버전 항목이 이미 있으면 skip (idempotent)
3. 파일 저장
```

### 3.3 파일 구조 규칙

- 각 차트 버전 디렉토리의 `CUSTOM-README.md`에 업그레이드 주의사항을 추가한다.
- `CUSTOM-README.md`는 `chart_updater`가 이전 버전에서 carry-over하므로 기존 배포 내용은 유지된다.
- `BUILD-README.md`는 차트 메타 정보(repo, 설치 명령어 등)를 유지한다.
- 별도의 `docs/upgrade.md`는 생성하지 않는다.

### 3.4 중복 방지

이미 해당 버전 업그레이드 섹션이 존재하면 덮어쓰기 또는 스킵한다 (설정으로 제어).

---

## 4. Git PR Bot 설계

### 4.1 자동화 단계

```
1. 새 branch 생성: update-{chart}/{to_version}
2. 카탈로그 신규 버전 디렉토리 커밋 (manifests/helm/<chart>/<to_version>/)
3. CUSTOM-README.md 업그레이드 주의사항 섹션 포함
4. git commit
5. PR 생성
```

### 4.2 PR 메타데이터

**PR 제목**:
```
update {chart}: {from_version} → {to_version}
```

**PR labels**:
- `needs-review` (breaking=true 시) — 담당자 확인 권장
- `auto-update` (breaking=false 시) — 자동 업데이트, 검토 선택적

**PR description**:
```markdown
## Helm Chart Update: {chart} `{from_version}` → `{to_version}`

**Severity**: `high`
**Breaking**: ✅ custom-values.yaml 수정 필요 (담당자 확인 권장)

### Breaking Changes
- `[values_key_removed]` ingress.enabled — custom-values.yaml에서 사용 중인 key 삭제

### Warnings
- `[service_port_changed]` Service/airflow-webserver — port 8080 → 8081

---
*Generated by update-catalog automation*
```

---

## 5. 관련 문서

- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Breaking Change 입력 생성
- [04-skill-interface.md](04-skill-interface.md) — `generate_upgrade_doc`, `create_pr` Skill