humanize-korean

Humanize Korean — AI Korean-tell removal orchestrator (v1.5)

v1.5 change notice (2026-04-26) — v1.1 baseline + Monolith Fast Path v1.2 (voice profile), v1.3 (candidate pool), and v1.4 (per-role model distribution) all failed to control hot-path cost, taking 25 minutes for a 5,000-character input. v1.5 rolls back to the simple v1.1 structure and then adds only a single-call monolith agent— that is the design.

Fast mode (default) — humanize-monolith The agent handles detection, polishing, and self-verification all in one call. 4 tool calls5 times. Wall-clock target of 2 for inputs of 5,000 characters or fewer3 minutes.

Strict mode (--strict) — the v1.1 five-person pipeline as-is (detector, rewriter, auditor, reviewer + taxonomist classification assets retained). Precise verification, long-form (8,000+ characters) handling, etc.

Removed: voice profile, candidate pool, promotion-checklist, sample-collection, authority hierarchy §1–§6.

Retained: the core classification system (new patterns from v1.2–v1.3.1 such as C-9, C-10, D-7, H-3, I-3, I-4), rewriting-playbook, five-agent definitions (strict mode backbone).

Phase 0: Context check and mode decision

At the start of work, first output the following single line to the user.

humanize-korean v1.5 — {fast|strict} 모드 / run_id: {YYYY-MM-DD-NNN}

Mode decision

If the user --strict·explicitly states "precise mode"·"five-person pipeline" → strict
Input exceeds 8,000 characters → strict (automatic upgrade + one-line notice to the user)
Everything else → fast (default)

run_id decision

Based on cwd, _workspace/{YYYY-MM-DD-NNN}/ newly generated (NNN is that day's sequence).
In the case of a partial re-run signal ("just this category again"·"second-pass polishing"), reuse the existing run_id + automatically upgrade to strict mode.

Fast mode (default)

Phase 1: Save input

Based on cwd, _workspace/{run_id}/ create
Save the input text to 01_input.txtsave to
Auto-estimate the genre from the first 300 characters (user specification takes precedence)

Phase 2: Monolith call

humanize-monolith Call the agent once with the Agent tool.

Input:

input_path: <abs path>/_workspace/{run_id}/01_input.txt
quick_rules_path: <abs path>/.claude/skills/humanize-korean/references/quick-rules.md
genre_hint: 칼럼 | 리포트 | 블로그 | 공적 | null

Output (written directly by the agent):

_workspace/{run_id}/final.md — polished version
_workspace/{run_id}/summary.md — metrics, self-verification, highlights

The monolith performs all of the following within a single call (see the agent definition for details):

Load the quick-rules rulebook → detect patterns from memory + polish + check the 6 self-verification items
Auto-rollback if the change rate exceeds 50%
One partial re-run if self-verification is violated
Write final.md + summary.md

Phase 3: Deliver results

Return the following 4 items to the user:

One-line status: 완료. 변경률 X% / 등급 Y / 자체검증 N/6 통과
Polished text body (Markdown block)
Key table in summary.md (metrics + category detection + self-verification)
If grade B or below, "If precision verification is needed, --strictguide to the 5-agent pipeline"

Default wall-clock target: 5,000 characters or fewer 23분, 8,000자 57분.

Strict mode (`--strict` or automatic promotion)

v1.1 5-agent pipeline as-is. Use only when verification separation and the re-polishing loop are meaningful.

Phase A: Detection

ai-tell-detector call → 02_detection.json

Phase B: Polishing (loop up to 3 times)

korean-style-rewriter call → 03_rewrite.md + 03_rewrite_diff.json

Phase C: Parallel verification (agent team)

TeamCreate로 humanize-review-team composition:

content-fidelity-auditor → 04_fidelity_audit.json (semantic equivalence)
naturalness-reviewer → 05_naturalness_review.json (residual/over-polishing)

TeamDelete then branch according to the comprehensive judgment matrix:

fidelity	naturalness	Comprehensive	Follow-up
full_pass	accept / accept_with_note	Final approval	Phase D
full_pass	rewrite_round_2	Second polishing	Phase B recall (target finding)
full_pass	rollback_and_rewrite	Rollback then re-polish	Instruct the polisher to roll back the edit
conditional_pass	-	Retry only the rolled-back edit	Phase B recall
fail	-	Full rework	Full Phase B recall

When entering the second/third polishing, 03_rewrite_v2.md·v3.mdseparate versions with . **If unresolved after up to 3 times, hold_and_report** human intervention.

Phase D: Final output

final.mdcopy the final polished text to
summary.md create (same format as fast mode)
Return results + grade + guidance to the user

Partial re-run / follow-up commands

User signal	Handling
"Only a specific category again"	Automatically switch to strict mode, re-run Phase B only for that category's finding
"Only this paragraph"	Strict mode, create a new run_id with only that paragraph as input
"Second polishing"·"`/humanize-redo`"	Of the existing run_id, `final.md`re-run strict Phase B with as the new input
"Adjust polishing intensity"	Strict mode, `min_severity` re-run from Phase A after changing the option
"Change the genre"	`genre_hint` re-run from Phase A after changing

Options (in natural language at the end of the arguments)

장르: 칼럼|리포트|블로그|공적 — specify genre (auto-estimated if omitted)
강도: 보수|기본|적극 — polishing intensity (default: basic)
최소심각도: S1|S2|S3 — detection threshold (default: S2)
--strict — force use of the 5-agent pipeline

Data flow summary

Fast mode (default)

01_input.txt
    ↓ [humanize-monolith — 단일 호출]
    ├ 메모리: quick-rules 로드 → 탐지 → 윤문 → 자체검증
    └→ final.md + summary.md

Strict mode

01_input.txt
    ↓ [ai-tell-detector]
02_detection.json
    ↓ [korean-style-rewriter]
03_rewrite.md + 03_rewrite_diff.json
    ↓ [병렬 팀]
    ├→ [content-fidelity-auditor] → 04_fidelity_audit.json
    └→ [naturalness-reviewer]      → 05_naturalness_review.json
    ↓ [오케스트레이터 종합]
    ├→ (재작업) Phase B로 복귀 (최대 3회)
    └→ (승인) final.md + summary.md

Agent invocation rules

Model: all unified to model: opus (v1.1 baseline). Model downgrading was attempted in v1.4, but the effect was minimal because the tool-call chain was the real bottleneck.

Agent definition location: Claude Code automatically searches in the following priority order.

<cwd>/.claude/agents/ (project local)
~/.claude/agents/ (global, this project is a project→global symbolic link)

Required agents (6 types):

humanize-monolith (new in v1.5, fast-only)
ai-tell-detector · korean-style-rewriter · content-fidelity-auditor · naturalness-reviewer (strict 5인 중 4명)
korean-ai-tell-taxonomist (maintain and extend the classification system — not called during this skill's execution, triggered only by a separate command)

Test scenarios

Fast normal flow

Input: AI column draft generated by ChatGPT (2,000–5,000 characters, rich in translationese, formulaic endings, hype vocabulary)
Expected: 15% change rate with a single monolith call25%, grade A/B, wall-clock 23 minutes, self-verification 5–6/6

Strict precision verification flow

User-specified --strict or 8,000+ character input
Run the 5-agent pipeline to the end, 18–22% change rate, verification team full_pass

Edge case — text already written by a human

Almost no matches in the monolith's own detection → change rate under 5% + a "possibly no editing needed" note in summary.md
The user can --strictforce verification

Precautions

Preservation of meaning is the supreme inviolable rule. In both monolith and strict, any violation is immediately rolled back.
Numbers, proper nouns, and direct quotations are not subject to detection/editing. Adhere strictly to the Do-NOT list.
No genre drift. A column does not shift into an essay, nor an essay into literature.
Preserve register. Formal input → formal output. AI-ness is grammar and rhetoric, not formality itself.
Change rate over 30% → warning, over 50% → forced stop.
No auto-loading. Do not automatically parse other files such as the project CLAUDE.md to infer options.

Reference materials

Slim rulebook (Fast-only): references/quick-rules.md — S1/S2 core patterns + self-verification checklist
Classification system main body (Strict-only): references/ai-tell-taxonomy.md — all 10 major categories × 40+ patterns
Editing prescriptions (Strict-only): references/rewriting-playbook.md — per-category substitution recipes and per-genre allowance tables
Web service spec (optional): references/web-service-spec.md — loaded when extending to web

About this skill

Phase 0: Context check and mode decision

Mode decision

run_id decision

Fast mode (default)

Phase 1: Save input

Phase 2: Monolith call

Phase 3: Deliver results

Strict mode (--strict or automatic promotion)

Phase A: Detection

Phase B: Polishing (loop up to 3 times)

Phase C: Parallel verification (agent team)

Phase D: Final output

Partial re-run / follow-up commands

Options (in natural language at the end of the arguments)

Data flow summary

Fast mode (default)

Strict mode

Agent invocation rules

Test scenarios

Fast normal flow

Strict precision verification flow

Edge case — text already written by a human

Precautions

Reference materials

Strict mode (`--strict` or automatic promotion)