/humanize-korean

name: humanize-korean
version: "2.3.0"
description: AI(ChatGPT·Claude·Gemini 등)가 쓴 한글 텍스트를 "사람이 쓴 글처럼" 윤문해주는 오케스트레이터 스킬. 번역투·영어 인용 과다·기계적 병렬·관용구·피동태 남용·접속사 남발·리듬 균일성·이모지/불릿 과다 등 10대 카테고리 70개 AI 티 패턴을 탐지·분류해 내용은 한 글자도 건드리지 않고 문체·리듬·표현만 자연스러운 한국어로 재작성한다. shim의 route_hint(light|standard|heavy)로 경로를 정해 잘 쓴 글은 1콜, 표준은 2콜, 중증·장문만 3+콜(진단→겨냥 윤문→finalize)로 처리한다. 트리거 — "AI 티 없애줘", "AI 같은 글 자연스럽게", "GPT/ChatGPT 문체", "AI 번역투 고쳐", "사람이 쓴 것처럼 윤문", "AI 윤문", "ChatGPT 티 제거", "한글 AI 탐지·윤문", "AI 글 사람처럼", "번역투 제거", "영어 인용 많은 글 윤문", "AI 글 티 안 나게", "휴머나이저", "humanize Korean", "AI detector bypass 한글". 후속 작업 — "특정 카테고리만 다시", "윤문 강도 조정", "장르 바꿔서", "이 문단만", "2차 윤문" 도 모두 이 스킬. 단순 맞춤법·오탈자 교정은 직접 처리, 번역은 번역 스킬, 내용 추가·삭제를 동반한 재작성은 별도 집필 스킬.

Humanize Korean — AI 한글 티 제거 오케스트레이터 (v2.3)

> **v2.3.0** — 구조 수렴 게이트(`verify_gates.py` 4축: 목표달성·대구 전멸·수치·golden) + 진단 슬림 인덱스(`diagnosis-rules.md`, taxonomy 83%↓). (v2.2: route_hint 3경로 + 단일 콜 우선) > 버전 히스토리·실측 근거·테스트 시나리오: [`references/design-notes.md`](references/design-notes.md)

Phase 0: 컨텍스트 확인 및 경로 결정

작업 시작 시 가장 먼저 다음 한 줄을 사용자에게 출력한다.

humanize-korean v2.3 — 경로: {light|standard|heavy} ({route_hint|사용자 지정}) / run_id: {YYYY-MM-DD-NNN}

(경로는 Phase 1의 shim 실행 후에 확정되므로, 이 상태 줄은 shim 직후 출력한다.)

경로 결정 규칙

1. **사용자 명시가 최우선.** `--strict`·"정밀 모드"·"정밀하게"·"제대로" → **heavy 고정**. "가볍게"·"빠르게만" → **light 고정**. 명시가 있으면 route_hint는 무시한다. 2. 명시가 없으면 shim이 `00_metrics.json`에 쓴 **`route_hint`**(`light`|`standard`|`heavy`)를 디폴트 경로로 따른다. 3. `route_hint` 필드가 없거나 shim이 graceful degrade로 점수 산출에 실패한 경우 → **standard**로 간주. 4. light/standard 결과가 등급 C/D → 사용자에게 "heavy(정밀) 재실행 권고" 안내(자동 전환 아님 — 사용자 opt-in). 5. **입력 길이는 경로를 바꾸지 않는다.** 1만자급도 단일 콜로 처리한다(§설계 노트의 실측 근거 참조). 길이·중증도 판단은 shim의 route_hint에 위임한다.

run_id 결정

• 모든 경로는 **cwd 기준**. 새 폴더 생성도 cwd 기준 `_workspace/{YYYY-MM-DD-NNN}/`에 만든다.
• 기존 시퀀스 확인은 **`Glob` 도구**로 표지 파일을 매칭해 간접 조회.

올바른 사용법: `Glob(pattern="_workspace/YYYY-MM-DD-*/01_input.txt")` → 결과에서 폴더명 추출 후 NNN 최댓값 + 1. 주의: Glob은 디렉토리 자체는 매칭하지 못한다. 반드시 그 안의 표지 파일(`01_input.txt`)을 매칭할 것. `Bash ls`는 OS·셸 환경에 따라 경로 해석이 달라지므로 사용 금지.

• 당일 폴더가 없으면 NNN = 001. 있으면 마지막 NNN + 1.
• 부분 재실행 신호("이 카테고리만 다시"·"2차 윤문")일 경우 기존 run_id 재사용 + heavy 경로로 자동 승급.

Phase 1: 입력 저장 + 정량 사전 점수 (input shim — 전 경로 공통)

1. cwd 기준 `_workspace/{run_id}/` 생성 2. 입력 텍스트를 `01_input.txt`에 저장 3. 첫 300자로 장르 자동 추정 (사용자 명시 시 우선) 4. 사전 처리 shim을 Bash로 1회 실행:

   python3 scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre}

• `--genre` 값은 영문 키: `essay | column | report | blog | abstract` (생략 시 `essay`). 장르 힌트 매핑: 칼럼→`column`, 리포트→`report`, 블로그→`blog`, 공적/기타→`essay`.
• `--run-dir`는 프로젝트 루트 기준 상대 경로 허용 (스크립트가 절대화). 그 외 인자: `--text`(run-dir 없이 즉석 실행 시 새 run 디렉토리 자동 생성), `--baseline`(baseline JSON 경로 override, 평소 불필요), `--diagnosis`(진단 텍스트 파일을 점수 블록 앞에 prepend — standard·heavy의 진단 결합용).
• 산출: `00_metrics.json`(정량 점수 + **`route_hint`**) + `01_input_with_metrics.txt`(점수 블록을 원문 앞에 붙인 결합 파일).
• **graceful degrade 내장**: metrics 계산이 실패하면 shim이 점수 블록 없이 원문만 감싼 결합 파일을 쓰고 `00_metrics.error`를 남긴다. 이 경우 route_hint 없음 → standard 경로.

5. `00_metrics.json`의 `route_hint`를 읽어 Phase 0 규칙대로 경로를 확정하고 상태 줄을 출력한다.

**단일 콜 우선 — 청킹은 여기서 하지 않는다.** `--chunk`는 heavy 경로 전용이며, 그때도 청크 경로를 탈지는 shim이 실제로 청크를 2개 이상 만들었는지로 정한다(heavy 절 참조).

Light 경로 (1콜) — 잘 쓴 글

어휘 티가 거의 없고 구조 티만 미미한 글. 목표는 **과윤문 방지**이지 많이 고치는 게 아니다.

1. **진단 생략.** `humanize-monolith`를 `Agent` 도구로 1회 호출 — 청킹 없음.

• 입력: `input_path=01_input_with_metrics.txt`, `quick_rules_path=${CLAUDE_SKILL_DIR}/references/quick-rules.md`, `genre_hint`, 그리고 강도 지시 `보수`(원문에 없던 표현 삽입 금지, 확신 없는 구간은 그대로 둔다).
• 출력: `final.md` (본문 + `<!-- HUMANIZE-SUMMARY -->` 블록).

2. Phase 2.5 변경률 게이트(Bash — LLM 콜 아님). 3. **조기 종료 보고**: monolith 탐지가 거의 없고 게이트 변경률이 5% 미만이면, 결과 전달을 "이미 좋은 글입니다 — 손댄 곳은 {N}곳({요지}) 정도"로 요약한다. 억지로 더 고치지 않는다. 4. 게이트 exit 2(≥50%)일 때만 롤백 재실행 1회(이 경우 총 2콜). light에서 50%가 나오면 과윤문 사고이므로 재실행 지시에 보수 강도를 재강조한다.

**콜 수: 1 (게이트 실패 시 최대 2).**

Standard 경로 (2콜) — 보통의 AI 초안

1. **진단 1콜**: `humanize-diagnostician`을 `Agent` 도구로 1회 호출.

• 입력: `input_path=01_input_with_metrics.txt`, `taxonomy_path=references/diagnosis-rules.md` (진단 전용 슬림 인덱스 — 71패턴 전수, taxonomy에서 자동 생성)
• 출력: `02_diagnosis.md` — 글 전체의 **지배 패턴 3~6개**(본진 ID + 근거 + 처방) + 장르·격식 + 보존 지침.
• 진단은 span을 세지 않는다. "무엇이 이 글을 지배하는가"를 판단한다(안정적).

2. shim으로 진단을 monolith 입력 앞에 결합 (Bash — LLM 콜 아님):

   python3 scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre} --diagnosis _workspace/{run_id}/02_diagnosis.md

→ `01_input_with_metrics.txt`가 [진단 → 정량 블록 → 원문] 순으로 재생성된다. 3. **윤문 1콜**: `humanize-monolith` 1회 호출 — **청킹 없음. 1만자급도 단일 콜이다.** → `final.md`. 4. Phase 2.5 변경률 게이트(Bash). 5. **finalize 생략이 기본.** 과윤문은 `verify_gates.py`의 결정적 게이트가 잡는다. finalize 승급 조건(아래 표)에 걸릴 때만 `humanize-finalizer` 1콜 추가(이 경우 총 3콜).

**콜 수: 2 (finalize 승급·게이트 롤백 시 3).**

Heavy 경로 (3+콜) — 중증 AI 슬롭·검증 증적 필요

`--strict`·"정밀 모드"의 강제 대상. 진단→겨냥 윤문→finalize의 완전한 3콜 구조.

Phase P1: 진단

Standard의 1과 동일 — `humanize-diagnostician` 1콜 → `02_diagnosis.md`. 장문이라도 진단은 통짜 1콜(전 청크 공유)이다.

Phase P2: 겨냥 윤문

1. shim으로 진단 결합 (Bash). **heavy에서만** `--chunk`를 함께 줄 수 있다:

   python3 scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre} --diagnosis _workspace/{run_id}/02_diagnosis.md --chunk

• 분할 여부·경계는 100% shim(Python)이 정한다(문단·문장 경계, 헤딩 승격, 말미 각주 passthrough — 청킹 임계는 shim 관리).
• 산출: `01_chunk_{NN}_input_with_metrics.txt` N개 + `chunk_manifest.json`.

2. **청크 경로 판정**: `chunk_manifest.json`의 body 청크(passthrough 제외)가 **2개 이상일 때만** 청크 경로. **1개면 단일 monolith 콜로 처리한다** — 청킹은 shim의 결정이지 오케스트레이터의 추측이 아니다. 단일 콜로 처리할 때의 입력 파일도 manifest가 있으면 그 청크의 `input_file` 값을, 없으면 `01_input_with_metrics.txt`를 쓴다. 3. **단일 콜(기본)**: `humanize-monolith` 1회 호출(`input_path=01_input_with_metrics.txt`). monolith는 진단문을 앞머리에서 읽고 지배 패턴을 겨냥해 윤문한다. → `final.md`. 4. **청크 병렬(shim이 실제로 쪼갠 경우만)**:

• 각 body 청크를 monolith로 **병렬 호출**(동시 최대 4). 입력·출력 파일명은 manifest의 **`input_file`·`rewritten_file` 필드를