# Skills 구현 태스크 (Step 1)

## 목표

Agent(OpenClaw/Nanobot)가 직접 호출할 수 있는 Skill들을 구현한다.
파이프라인 오케스트레이션 코드는 구현하지 않는다. 순서 제어는 Agent가 담당한다.

> **범위**: 각 Skill이 독립적으로 호출 가능한 상태. Skill 간 호출 순서 코드는 제외.

---

## 태스크 목록

### 🔴 높음 (핵심 기능)

#### T1. Helm Diff Engine 구현 (`helm_diff` Skill)
- [ ] **dip-catalog 경로 지원**: `chart_path` 입력으로 `manifests/helm/<chart>/<version>/` 직접 사용
- [ ] 신규 버전 감지 시 `manifests/helm/<chart>/<new>/` 디렉토리 생성 (기존 유지)
- [ ] 최신 차트 pull + 압축 해제 후 신규 버전 디렉토리에 반영
- [ ] (repo 구조) `helm pull`로 두 버전 다운로드
- [ ] (dip-catalog) 로컬 디렉토리 복사로 `chart_old/chart_new` 구성
- [ ] values.yaml flat key 비교 (added / removed / changed / type_changed)
- [ ] **`custom-values.yaml` 기본 적용** (values_override 기본값)
- [ ] `helm template` 렌더링 후 리소스 단위 비교
- [ ] CRD schema 비교 (schema / required / version / webhook)
- [ ] dependency (Chart.yaml) 비교
- [ ] Structured Diff JSON 스키마 확정 및 출력

**완료 기준**: 임의의 두 chart 버전에 대해 Structured Diff JSON이 정상 생성됨

#### T2. Breaking Change Rule Engine 구현 (`breaking_change_check` Skill)
- **Breaking 정의**: `custom-values.yaml`을 수정해야 하는 상황 (카탈로그 맥락)
- [ ] Values key 삭제 감지 — custom-values.yaml에 해당 key 있을 때만 breaking, 없으면 warning
- [ ] Values type 변경 감지 — 동일 기준 (custom-values.yaml에 있을 때만 breaking)
- [ ] Service port / type 변경 감지 — ⚠️ warning (custom-values.yaml 수정 불필요)
- [ ] resource 삭제 감지 — ⚠️ warning (custom-values.yaml 수정 불필요)
- [ ] Dependency major version 변경 — custom-values.yaml에 해당 subchart prefix key 있을 때만 breaking
- [ ] CRD required field 추가 / field 삭제 / storage version 변경 감지
- [ ] severity 분류 (critical / high / medium / warning)

**완료 기준**: custom-values.yaml 기준으로 올바르게 breaking/warning 분류, False Positive 최소화

#### T3. LLM Summarizer 구현 (`generate_upgrade_doc` Skill)
- [ ] Structured Diff JSON + Breaking 결과를 LLM API에 전달
- [ ] **docs_context 반영**: README/BUILD/CUSTOM 요약을 참고 컨텍스트로 포함
- [ ] Prompt 구현 (설계 문서 기반)
- [ ] 토큰 예산 관리 (50,000 token 상한, 초과 시 중요도 기반 필터링)
- [ ] Markdown 출력 검증 (형식 일치 여부)

**완료 기준**: 생성된 Markdown이 설계 문서의 Output Format을 준수하고, 없는 내용을 만들어내지 않음
- breaking=true → LLM 상세 가이드 (USE_CLAUDE_CLI=1 필요)
- breaking=false → 템플릿 기반 간단 요약
- 항상 실행 (breaking 여부와 무관)

#### T3-1. CUSTOM-README.md 업그레이드 주의사항 추가
- [ ] generate_upgrade_doc 결과를 `CUSTOM-README.md`의 `# Upgrade History` 섹션에 추가
- [ ] `update_docs_file` Skill 호출: `docs_file="manifests/helm/<chart>/<to_version>/CUSTOM-README.md"`

#### T4. Skill 인터페이스 구현
- [ ] `helm_diff` Skill 구현 및 노출
- [ ] `breaking_change_check` Skill 구현 및 노출
- [ ] `generate_upgrade_doc` Skill 구현 및 노출
- [ ] `update_docs_file` Skill 구현 및 노출
- [ ] `create_pr` Skill 구현 및 노출
- [ ] `deploy_validate` Skill 구현 및 노출
- [ ] 인터페이스 버전 `1.0` 확정

**완료 기준**: 각 Skill이 독립적으로 호출 가능하고 입출력 스키마가 문서와 일치

---

### 🟡 중간 (안정성)

#### T5. 에러 처리 및 Fallback
- [ ] `helm pull` 실패 시 재시도 (3회) + 알림
- [ ] `helm template` 렌더링 실패 시 partial diff 생성
- [ ] chart 미존재 시 스킵 + 로그
- [ ] 네트워크 타임아웃 (60s) 처리
- [ ] 각 Skill의 오류 시 에러 응답 포맷 일관화

#### T6. Chart Version Detector 구현
- [ ] **dip-catalog 디렉토리 스캔** (`manifests/helm/<chart>/` 하위 버전 변화 감지)
- [ ] **git diff 기반 신규 버전 탐지**
- [ ] ArtifactHub API 연동
- [ ] Helm repo `index.yaml` 스캔
- [ ] GitHub Release Webhook 수신
- [ ] Cron 스케줄 설정

#### T7. Docs Updater 구현 (`update_docs_file` Skill)
- [ ] `CUSTOM-README.md`에 `# Upgrade History` 섹션 추가 (기존 내용 유지)
- [ ] 대상 경로: `manifests/helm/<chart>/<to_version>/CUSTOM-README.md`
- [ ] 중복 버전 처리 (overwrite 옵션)
- [ ] `BUILD-README.md`는 `chart_updater`가 carry-over + 버전 번호 치환으로 관리 (update_docs_file 대상 아님)

#### T8. Git PR Bot 구현 (`create_pr` Skill)
- [ ] branch 생성 (`helm-upgrade/{chart}/{version}`)
- [ ] commit (chart version 업데이트 + docs 수정)
- [ ] PR 생성 (제목, labels, machine-readable metadata 블록 포함)

#### T9. Deploy Validator 구현 (`deploy_validate` Skill)
- [ ] `helm upgrade --dry-run` 실행
- [ ] test namespace에 `helm upgrade` 배포
- [ ] Pod Running + Ready 상태 확인 (타임아웃: 5분)
- [ ] 비정상 K8s events 수집
- [ ] 실패 시 Pod 로그 수집
- [ ] namespace teardown

---

### 🟢 낮음 (개선)

#### T10. 사용자 정의 values 오버라이드 지원
- [ ] `values_override` 파일 경로 또는 inline YAML 지원
- [ ] Diff 생성 시 오버라이드 values 적용
- [ ] **dip-catalog 기본값**: `custom-values.yaml` 존재 시 자동 적용

---

## 구현 진행 현황

- 현황 표는 [docs/status.md](../status.md)에서 관리

---

## 우선순위 요약

```
T4 (Skill 인터페이스 스키마 확정) ← 가장 먼저 (다른 모든 태스크의 계약)
    ↓
T1 (Helm Diff) + T2 (Rule Engine)  ← 병렬 구현 가능
    ↓
T3 (LLM Summarizer) → T3-1 (CUSTOM-README.md 업그레이드 주의사항 추가)
    ↓
T7 (Docs Updater) + T8 (PR Bot) + T9 (Deploy Validator)  ← 병렬 구현 가능
    ↓
T5 (에러 처리) + T6 (Version Detector) + T10 (values 오버라이드)
```

---

## 완료 기준 (Step 1 전체)

- [ ] 각 Skill이 독립적으로 호출 가능
- [ ] airflow chart 임의 두 버전에 대해 각 Skill 단독 동작 확인
- [ ] Breaking Change가 있는 버전과 없는 버전 모두 올바르게 처리
- [ ] 생성된 PR에 machine-readable metadata 블록 포함
- [ ] 에러 발생 시 해당 Skill만 실패하고 에러 응답 반환 (전체 중단 없음)
- [ ] Skill 인터페이스 버전 `1.0` 확정

---

## 관련 설계 문서

- [design/01-helm-diff-engine.md](../design/01-helm-diff-engine.md)
- [design/02-breaking-change-rules.md](../design/02-breaking-change-rules.md)
- [design/03-llm-summarizer.md](../design/03-llm-summarizer.md)
- [design/04-skill-interface.md](../design/04-skill-interface.md)