korean-docs — Korean document writing and review

Core

Prioritize meaning and evidence, the explanation the reader needs, natural Korean and appropriate register, then concision. Write complete prose and review it before commit. The korean-skills plugin is an optional precision upgrade, not a requirement.

Writing rules

• Structure: Put the conclusion or summary first and evidence and detail after. Use concrete noun-phrase headings that reveal the document's flow.
• Paragraphs: State one claim per paragraph. Usually use two to four sentences, but use a shorter or longer paragraph when the claim needs it.
• Source lines: In prose paragraphs and prose in list items, put each complete Markdown sentence on its own source line. Do not hard-wrap a sentence; add a blank line only when its meaning or topic changes. Tables, code blocks, commands, and quotes are exempt, subject to repository formatter precedence.
• Forms: Use lists only for parallel items and tables for repeated-field comparisons. Reserve emphasis and callouts for decisions or warnings.
• Style: Default to complete declarative sentences ("~한다/~이다") for documents; follow an explicitly requested register or an established audience-specific format. Use 개조식 only inside lists and tables. Do not inherit a chat reply's register automatically.
• Audience: Identify what the intended reader knows. Define an unfamiliar necessary term in familiar words on first use and connect it to a concrete example from the source. For causes, explain the conditions, sequence, and consequence; for decisions, explain the relevant trade-offs and limits. Do not invent an incident or a measured result to make an example vivid.
• Natural Korean: Check grammatical correctness, natural word order, subject-predicate agreement, modifier proximity, particles, tense, and honorific consistency.
• Terms: Replace English noun chains and long noun phrases with active Korean sentences that have verbs. Prefer concrete words over abstract or Hanja-heavy wording, define a technical term briefly on first use, then use it consistently.
• Fidelity: Do not add unsupported qualifiers. Preserve exact numbers, units, paths, commands, code, and error messages.
• Language-quality checks shared with korean-chat flag translationese (attach particles directly), double passives, "가지고 있다", AI cliché vocabulary (핵심적·효과적·혁신적·원천적으로), and unnecessary commas for contextual review. A matching word is not itself an error; preserve a grammatical expression that conveys necessary meaning.
• Keep enough explanation for the reader to understand or act. Do not shorten away a prerequisite, reason, condition, exception, or distinct supported property to fit a line count or style pattern.
• Formatter: Follow repository formatting and writing rules when they conflict with these rules, and record the exception in the review findings.