self-improve git:20260706.ffc7073A

Immutable. This exact content is served forever at /api/v1/blob/947aebb7c61e827a.

---
name: self-improve
description: Propose improvements to agent/skill/rule definitions from accumulated feedback-ledger defects and eval reports. Proposal-only - applies changes exclusively after evals show no regression AND the user approves. Trigger with /self-improve.
model: opus
effort: high
---

# Self-Improve

feedback ledger에 누적된 **반복 결함**을 근원(에이전트·스킬·룰 정의)에 반영하는
재귀 개선 루프 — 단, **제안-전용(proposal-only)**이다. 적용은 게이트를 통과해야만 한다.

<HARD-GATE>
정의 파일(.md) 수정을 **적용된 상태로 남기려면** 다음 전부 충족:

1. **커버리지 판정 선행**: 수정 대상에 대응하는 eval 시나리오(`evals/scenarios/<agent>/`)가
   있는가?
   - **있음** → 관련 evals(`--agent <name>`)가 baseline 대비 후퇴 없음(진짜 회귀 없음)
   - **없음**(스킬·룰·시나리오 없는 에이전트) → **eval 게이트는 미적용이다.**
     exit 0을 "게이트 통과"로 계산·보고하는 것은 게이트 착시(false-green)이며 금지.
     "EVAL COVERAGE 없음 — 사용자 승인이 유일한 게이트"임을 명시 고지한다.
2. 사용자가 diff를 보고 **명시적으로 승인**

evals 실행 불가(exit 2 SKIPPED)면 제안까지만 — SKIPPED를 통과로 위장 금지.
자동 커밋 금지 — 커밋은 항상 사용자/메인 세션의 별도 결정.
**승인 전의 워킹 트리는 항상 깨끗해야 한다** (아래 4단계: 모든 분기에서 롤백 후
승인 시에만 재적용 — 미승인 diff가 트리에 잔존하면 게이트 실패로 간주하고 중단).
</HARD-GATE>

> 위치 근거: 학습 루프(ledger→LESSONS)는 "같은 실수를 세션이 회피"하게 하지만,
> 결함의 근원이 정의 파일에 있으면 매 세션 회피 비용을 낸다. 이 스킬은 그 근원을
> 고치는 마지막 단계다. 안전망의 실체는 대상별로 다르다 — eval 커버리지가 있는
> 대상(현재 review-code·fix-bugs·implement-code)은 이중 게이트, 그 외에는
> **사용자 승인 단일 게이트**임을 숨기지 않는다.

## 절차

### 0. 전제

- repo root 기준으로 실행: `ROOT=$(git rev-parse --show-toplevel)` 후 모든 경로는
  `$ROOT` 기준 (CWD 가정 금지).
- 시작 시 `git status --porcelain`으로 대상 정의 파일들이 깨끗한지 확인 — 이미
  dirty면 사용자에게 보고하고 중단 (남의 변경 위에 제안을 얹지 않는다).

### 1. 입력 수집

- **ledger 전량**: `docs/works/feedback/ledger.md`를 **직접 읽는다** (읽기는 허용 —
  `feedback-loop.md`의 금지는 *편집*이다). `feedback.sh digest`는 세션 주입용으로
  1,200자에서 절단되므로 전수 분석 입력으로 쓰지 않는다.
- 최신 eval 자산: baseline은 `evals/baseline/`에서 **파일명 사전순 최대의
  `YYYY-MM-DD.json`** (`.bak`·`.gitkeep` 제외), 리포트는 `evals/reports/`의 최신 파일.
- **직전 적용분 멱등성 확인**: `git log --oneline -20 -- plugins/common/`에서 이전
  self-improve 적용 커밋의 대상 결함 패턴을 확인하고, 그 패턴은 이번 분석에서
  "이미 근원 조치됨 — 재발 시에만 재검토"로 배제한다 (ledger에는 addressed 표기
  수단이 없다 — 아래 5단계의 정직한 한계 참조).
- ledger 부재/비어있음 → "개선 대상 없음" 보고 후 종료.

### 2. 근원 분석

**frequency ≥ 2** 엔트리만 대상 (1회 결함은 노이즈 가능성 — LESSONS 회피로 충분):

- 결함 pattern → 그 결함을 만들었거나 막지 못한 정의를 식별
  (구현 결함→implement-code/implement-api 등, 리뷰 누락→review-code,
  절차 위반→skills/rules)
- eval 리포트의 실패/flake 이력도 역추적 (예: delegation signal flake →
  implement-code 계약 강화, 실사례)
- **대상별 커버리지 태깅**: 각 제안 대상에 `[eval-covered]` 또는 `[no-eval-coverage]`
  를 붙인다 — 이후 게이트 경로가 갈린다.
- 근원이 정의가 아니라 코드(hooks/scripts)면 범위 밖 — `fix-bugs` 위임 신호.

### 3. 수정 제안 (적용 아님)

대상 정의별 **최소 diff**: 무엇을(파일:섹션), 왜(ledger 엔트리·eval 증거 인용),
어떻게(diff). 순 증가 +15줄 초과는 근거 별도 명시(프롬프트 비대 = 부채).
frontmatter 규약/금지 필드 self-check.

### 4. 안전 게이트 — 항상 롤백, 승인 시에만 재적용

1. 제안 diff를 워킹 트리에 임시 적용.
2. `[eval-covered]` 대상만: `$ROOT/scripts/run-evals.sh --validate` 선행(스키마/인프라
   문제를 회귀와 분리) → 통과 시
   `$ROOT/scripts/run-evals.sh --agent <name> --compare <baseline>` 실행.
   - 출력에 "baseline 대비 후퇴 감지"가 있는 exit 1 → **진짜 회귀** — 제안 폐기 예정으로 표기
   - 그 외 exit 1(스키마 오류·매치 없음·baseline 읽기 실패) → **인프라 문제** — 회귀로
     오귀속 금지, 별도 보고
   - exit 2 → SKIPPED — 적용 보류 예정으로 표기
   - `[no-eval-coverage]` 대상: eval 실행 자체를 생략 (신호 0에 비용 지불 금지) —
     "커버리지 없음" 표기
3. **무조건 롤백**: 결과와 무관하게 임시 적용을 되돌린다. 롤백 후
   `git status --porcelain -- <대상파일>`이 **비어있음을 검증** — 비어있지 않으면
   "게이트 실패, 수동 개입 필요"로 즉시 중단.
4. 사용자에게 **깨끗한 트리 상태에서** 제시: 제안 diff + 근거 + 게이트 결과
   (진짜 회귀 → 이미 폐기됨을 보고 / SKIPPED·커버리지 없음 → 그 사실 명시).
5. **사용자가 승인한 항목만 재적용**. 미승인/부분승인 항목은 재적용하지 않는다 —
   트리는 이미 깨끗하므로 잔존물이 없다.

### 5. 사후 처리 — 정직한 한계 포함

- 적용 항목: 커밋 메시지에 ledger pattern 인용 권장(추적성) — 커밋은 사용자 결정.
- **ledger는 정리하지 않으며, 자동으로 소멸하지도 않는다**: `_decay`는 엔트리 수가
  상한(50)을 초과할 때만 frequency 하위를 제거한다 — 시간 만료(TTL)는 없다. 즉
  근원을 고쳐 재발이 멈춘 고빈도 엔트리도 ledger에 남는다. 이것이 다음 실행에서
  재제안 노이즈가 되는 것을 1단계의 멱등성 확인(직전 적용 커밋 대조)으로 막는다.
- 다음 `/self-improve` 실행 시 직전 적용 항목의 **재발 여부**(frequency 증가)를
  확인해 보고 — 증가했다면 근원 수정이 실패한 것이다.

## 비용 주의

eval 1회 실행은 실 API 호출이다 (시나리오당 수십 초~수 분). `--agent` 필터로 관련
시나리오만 돌리고, 제안이 여러 에이전트에 걸치면 배치로 묶어 1회 실행을 공유하라.

## 완료 기준

- freq≥2 엔트리 전수(ledger.md 직접 읽기 기준)에 대해: 제안 or 범위밖(위임) or
  보류 판정 + 근거
- 적용된 변경은 전부 게이트 기록(커버리지 유무 + eval exit + 승인)과 함께 보고
- 하나도 적용 못 해도 정직하게 보고 — "제안 0건 적용"은 실패가 아니라 상태다