Files
claude-harness/plugins/harness/skills/retro/SKILL.md
T
DongHyeonka f7e235bad7 feat(plugin): 장부가 회고 대기와 효과 판정을 세고 세션 시작에 알린다
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이다. 회고는 사람이
「주 1회」를 기억해야 돌고, 고친 뒤 효과가 없으면 되돌린다는 규칙을
적을 칸도 없다. 지난 4작업은 모두 실측이 p30 아래였는데(실측/p50
시간 중앙값 0.43), 매번 이유 한 줄만 바꿔서 치우침이 그대로 남았다.

고른 방법:
- precedents 끝에 보정 줄을 낸다: 실측/p50 중앙값(시간·호출·출력)과
  p30 아래·p80 위 건수. --ledger를 여러 번 받아 다른 repo 장부를 더한다.
  estimate 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄.
- pending은 예측 밖(p30~p80 밖이거나 why가 있음)인데 retro 줄이 없는
  작업만 보이고, 효과 판정이 없는 개선도 보인다.
- retro 줄에 fix(개선 id)·applied_at, 새 줄 verdict(effective·reverted).
  판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건의 실측이 끝나면 한다.
  개선 전에 예측한 작업은 그 개선의 영향을 받지 않아 세지 않는다.
- SessionStart에 ledger.py nudge를 따로 건다. startup일 때만, 같은
  repo(worktree를 git common dir로 묶어)에 20시간에 한 번 한 줄.
  append가 actual 줄을 쓸 때 예측 밖이면 그 자리에서 한 줄 알린다.
버린 대안: session-start 장부 훅에서 출력(장부 훅 출력 0 규칙을 깬다),
매 세션 넛지(하위 세션마다 같은 줄이 컨텍스트에 쌓인다), 별도
retro 스크립트(이미 있는 ledger.py 명령으로 충분하다).

위험: 넛지는 그 repo의 첫 세션이 하위 세션이어도 나온다. 문구에
「맡은 일이 회고가 아니면 넘긴다」를 넣었다. 다른 repo 장부에 retro
줄이 더해질 때까지 그 repo에서는 하루 한 번 넛지가 나온다.
보정 규칙은 같은 4건으로 잰 값이라 아직 효과를 모른다.

검증: scripts/check.sh rc=0(플러그인 시험 21개 OK, expected failure 1,
템플릿 시험 10개 OK, plugin validate --strict 통과). 새 조건 15개를
하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다. 백엔드 템플릿
장부에 nudge를 돌리면 「회고 안 한 빗나간 예측 3건」 한 줄이 나왔다
(상태 폴더는 scratchpad).
2026-11-08 23:09:32 +09:00

4.0 KiB

name, description
name description
retro Use when reviewing estimate misses in this repo's ledger — when the user asks for a retrospective ("회고해", "retro", "예측이 왜 틀렸나", "장부 정리"), at a weekly review, or when a task just closed with its actual time over p80 or under p30 — to classify why each estimate missed and pick exactly one harness fix in the order architecture → gate → instructions → user behavior. 장부에서 회고가 없는 실측 줄을 모아 틀린 이유를 나누고, 아키텍처 → 게이트 → 지침 → 사용자 행동 순서로 고칠 곳 하나를 고른다.

retro — 예측이 틀린 이유로 하네스 고치기

예측이 틀린 흔한 원인은 맥락 부족이다. 사람을 탓하지 않고 하네스(구조·검사·지침)를 고친다. 앞 단계로 풀리면 뒤 단계는 손대지 않는다.

장부 ──> 회고 안 된 실측 ──> 이유 분류 ──> 고칠 단계 하나 ──> 고친 커밋 ──> retro 줄(개선 id)
뒤 작업 2건 ──> 같은 이유가 되풀이됐나 ──> verdict 줄(유지 또는 되돌림)

1. 대상 모으기

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" pending
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" precedents

pending은 실측이 p30p80 밖이거나 why가 있는데 retro 줄이 없는 작업과, 판정 대기 개선을 보인다. p30p80 안이면 회고할 것이 없다(예측이 맞았다). 플러그인이 세션 시작 때 이 수를 하루 한 번 알린다. 다른 repo 장부는 --ledger <경로>로 본다.

2. 이유 나누기 — 아래 일곱 중 하나

cause 보이는 모양
지시 모호 완료 기준·범위가 brief에 없어 중간에 바뀜
착수 전 조사 부족 착수 뒤에야 안 사실(기존 장치, 제약)이 시간을 바꿈
아키텍처 경직 작은 변경이 여러 경계를 건드림
검증 대기 게이트·빌드·원격 실행 대기가 시간 대부분
외부 대기 사람 승인, 권한, 다른 세션
범위 변경 일 도중 요청이 늘거나 줄어듦
예측 근거 없음 선례를 잘못 읽었거나 배수에 근거가 없었음

세션 기록이 필요하면 ledger.py usage <uuid>로 다시 센다.

3. 고칠 곳 하나 — 이 순서로

  1. architecture: 구조나 도구를 바꿔 같은 일이 다시 안 생기게(스크립트, 경계 정리, 장부 칸).
  2. gate: 검사·훅이 잡게.
  3. instructions: AGENTS.md·스킬·playbook에 한 줄.
  4. user: 사용자에게 바꿔 달라고 할 행동(brief 양식 등).

앞 단계로 풀 수 있는데 뒤 단계(지침 한 줄 더하기)를 고르지 않는다. 고친 것은 커밋으로 남긴다.

4. retro 줄

echo '{"kind":"retro","task":"<작업 이름>","cause":"예측 근거 없음","level":"instructions","note":"<무엇을 왜>","ref":"<커밋이나 문서>","fix":"<개선 id>"}' \
  | python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append

하네스를 고쳤으면 fix에 짧은 개선 id를 붙인다(적용 때 applied_at은 빼면 지금). 고치지 않고 기록만 하는 줄은 fix를 뺀다. 여러 작업이 같은 개선으로 묶이면 첫 retro 줄에만 fix를 붙인다.

5. 효과 판정 — 고친 뒤 실측으로

pending에 「판정할 때다」가 나온 개선(적용 뒤에 예측한 다른 작업 2건이 실측까지 끝남)은 그 실측들에서 같은 이유가 되풀이됐는지 본다.

echo '{"kind":"verdict","task":"<판정한 작업>","fix":"<개선 id>","effect":"effective","evidence":"<뒤 작업과 그 실측>"}' \
  | python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ledger.py" append
  • 되풀이되지 않았으면 effective(유지).
  • 되풀이됐으면 그 수정을 되돌리는 커밋을 만들고 reverted와 ref(되돌린 커밋)를 쓴다. 그다음 같은 이유를 다른 단계로 다시 고른다.
  • 판단할 실측이 아직 모자라면 쓰지 않고 기다린다.