Gyanesh5/plain-zh

plain-zh: Plain Chinese

Chinese written for humans: define terms before using them, use one name for one concept, keep metaphors out of headings, and keep the structure straightforward.

Each rule ends with an evidence level annotation:

• 〔Empirical〕 Based on 270 paired corpora with same-topic, same-fact content from lieflat-less-ai-tone, with two rounds of consistent results.
• 〔Cognitive〕 Cognitive science foundations (Pinker's curse of knowledge, Cowan's working memory capacity).
• 〔Engineering〕 Mature engineering practices (ASD-STE100 controlled writing, Chinese Copywriting Guidelines).
• 〔Convention〕 Design conventions of this project, without experimental evidence; adjustable as needed.

Two Modes

Generation Mode (loaded before writing): Determine the audience and glossary before writing; after writing, self-check against P1-P7. POLICY.md is an 8-line condensed version of this mode, suitable for embedding in AGENTS.md / CLAUDE.md / SOUL.md for persistent use.

Review Mode (operating on finished text): Follow the "Review Mode Workflow" to produce a report, wait for confirmation, then rewrite.

Project Glossary Mechanism

Both generation and review first check the project's glossary sources before writing:

1. Glossary Source Priority: User's current instruction > project glossary (CONTEXT.md, GLOSSARY.md, term comparison table) > this specification's defaults. Use project terms as defined; do not rewrite existing terms according to this specification.
2. Coexistence with Third-Party Workflows: When the project runs skills like mattpocock's (wayfinder, to-spec, etc.), their CONTEXT.md terms, commands, and metaphorical words (wayfinder=mission map, grill=interrogation and adjudication, to-tickets=break into implementation tickets, 到站=goal achieved, 进雾=pending for now) are consumed as project conventions; interface terms are handled in a dual-track manner per P3.
3. Incremental Governance: Do not rewrite existing documents; prioritize the evidence chain of decision archives. If the project has no glossary and a single review hits 3 or more uncompared terms, suggest creating a term comparison table at the end of the report; subsequent new documents will follow the comparison table.

R1 Terminology Discipline

P1 Define Before Use 〔Cognitive〕

Any term, abbreviation, filename, field name, or tool name must be defined or given a Chinese-English equivalent before its first appearance. It must not appear out of the blue. How to judge: Has the reader seen this term before? If not, use one sentence to introduce what it is.

• Before: "Just run build_assets.py."
• After: "First, use the repository's built-in resource packaging script build_assets.py to package, then run." (Use an appositive directly, without parentheses; if parentheses are truly needed, see P18.)

Exceptions: Terms already defined earlier in the text; common-sense terms for the target audience.

P2 Same Concept, Same Term 〔Empirical〕

Use one name for one concept from beginning to end. Do not rotate synonyms or invent new terms mid-text.

Evidence: Synonym renaming occurs 0.83-0.86 times per paragraph in AI text vs. 0.49 in human text; paragraphs with more than 2 occurrences: AI 20.6-22.5%, human 8.4%.

• Before: In the same paragraph, "optimize / enhance / improve" are used interchangeably for the same thing.
• After: Consistently use "optimize" throughout the text.

Exceptions: Literary variation in reference; "also known as X" when formally introducing a term.

P3 First Appearance with Equivalent; No Self-Made Translations 〔Engineering〕

For terms with a widely accepted translation, use the accepted one; for those without, write "Chinese (English)" at first appearance, then use Chinese thereafter. Do not invent jargon-like translations or statistical jargon.

• Before: "模板 chrome 五件套" "众数回归" "离众数"
• After: "Template UI elements (chrome): eyebrow title, metadata string, dash label" "Regression to the mean"

Exceptions: Fixed industry English terms (API, CI/CD); terms that the team has agreed to keep in the original language (see project glossary).

Interface Term Dual-Track: Slash commands, labels (Label, Status, Type), and configuration keys are agent invocation interfaces; keep them in the original language without translation. However, when they appear in human prose, provide an equivalent at first occurrence.

• Before: "For ticket 05, first confirm with the user when grilling."
• After: "For ticket 05, first confirm with the user when grilling (interrogation and adjudication)."

Machine metadata lines (Label, Status, Blocked by, etc.) should be grouped in a metadata section at the file header, not scattered in the body. Section headings should use Chinese, or Chinese-English bilingual format; do not keep entire headings in English.

P4 Metaphor Quota 〔Convention〕

Each concept gets at most one metaphor. Metaphors should only appear in explanations, not in headings, and should not be used repeatedly as terms. Models cannot judge metaphor appropriateness (inter-model consensus 0-40%), and post-hoc filtering is unreliable, so limit them at the source.

• Before: Heading "1. Origins and the Problem It Solves"; "Three Pillars / Pillar One / Pillar Two" as chapter framework.
• After: Heading "1. Origins: What Problem Does It Solve?"; "Three Principles / Principle One".

Exceptions: Style explicitly required by the user; metaphors confirmed effective in teaching scenarios (one per concept).

R2 Audience Calibration

P5 Audience and Known Items List 〔Cognitive〕

Before writing, determine two things: who the audience is and what they already know. Only reference concepts the reader has already established. The curse of knowledge: what the author knows, the reader may not, and authors most easily overlook this gap.

P6 Undefined Abbreviation Quota 〔Cognitive〕

At most 1 undefined abbreviation per 100 characters. Working memory holds about 4 unfamiliar items at a time; consecutive abbreviations force the reader to "pause and wonder." If the quota is exceeded, either expand or remove some.

P7 Cross-Domain Concepts Need Analogies 〔Cognitive〕

When introducing a concept outside the reader's domain, provide an analogy within the reader's domain, and explain the analogy's failure boundary. The analogy handles introduction; the boundary prevents distortion.

－ Example: "A register is like a parking space: each space holds only one value. But a register has no 'full' state; writing overwrites."

R3 Structural Signals

Ordered by strength of evidence. A hit is not an accusation; it's a prompt. Always return to the context to judge whether it applies.

P8 Rebuttal Framing 〔Empirical, 3.4x〕

"Not X, but Y" / "You might think... actually..." / "Seemingly... in fact..." / "Rather than X, it's more like Y." In most cases, make the judgment directly.

• Before: "The model isn't copying; it's regressing to the mean."
• After: "The model isn't plagiarizing; it outputs the statistically most common phrasing."

Exceptions: Correcting a genuine misunderstanding ("The error occurs during the save phase, not the upload phase.").

P9 Prompt Colon 〔Empirical, 3.8x〕

"In summary:" / "The core is:" / "The key is:" / "The reasons are:". If the prompt carries no information, delete it and write the conclusion directly. If the first half truly connects to the previous text, just replace the colon with a period.

P10 Chain of Continuity 〔Empirical: AI median 7, human 2〕

Each paragraph's opening picks up on the key word from the end of the previous paragraph, creating a zero-jump flow. Leave 1-2 natural jumps in the chain to allow the reader to participate in reasoning.

Exceptions: Tutorials, legal documents, and other genres that require tight connection.

P11 Isomorphic Triple 〔Empirical: AI 29.4%, human 10.7%〕

Three consecutive sentences sharing the same syntactic skeleton (same opening structure, same closing rhythm). Break up one of them: merge, split, or change word order—do not delete content.

Exceptions: Deliberate rhetoric (speeches, manifestos); list-style content; three items in a narrative sequence.

P12 Four Translation-Speak Structures 〔Empirical〕

Only handle these four: excessively long pre-nominal modifiers (more than 15 characters before the head noun, or two consecutive "的"); "when..." fronted subordinate clauses; "for..." / "as far as... is concerned" topic shells; consecutive paragraph openings with "However, / Therefore, / In addition," as signposts. Break them up when possible; keep them if they genuinely serve a temporal or logical function.

P13 Enumeration and Compression Density 〔Empirical: Comma-enumerated lists AI 3.21 vs human 1.78 per 1000 characters; paired retest dense coordination AI 1.45x, two rounds consistent〕

A single clause should not contain more than 3 coordinated items. If exceeded, expand into a list or summarize with a link to the source. Do not use counting collective terms—"monitoring four" / "diff three-piece set" / "comparison six-piece set". Either list each item individually, or define them first and then use the abbreviation. Same rule applies to slash-enumerated items.

• Before: "M7 includes page redo/parameter importance/bad epoch early stop/monitoring four/Retry/form"
• After: "M7 includes six items: Agent page redo, parameter importance analysis, bad epoch early stop, four monitoring items (GPU curve, time estimation, desktop notification, loss dual line), one-click Retry, and form refactoring."

Exceptions: Command-line arguments, error code tables, list-style documents' natural enumerations; three-item comma coordination is normal writing (X-level lesson: in-sentence parallelism is common in human text); only process when there are 4+ items with the same structure.

P14 Word List Downgrade 〔Empirical: Not significant〕

Hits from the word list ("empower," "grasp," "closed loop," "deepen," "precipitate," etc.) only trigger a low-weight prompt; they are not standalone reasons for modification. Structural signals (P8-P12) take priority over the word list.

X-Level (Never Change): The following features show no distinguishing power or opposite direction in paired retests; do not change even if detected—ordinal-number subheadings, "This means" type restatements, empty-turn sentences introducing lists, "First / Next / In summary," rhetorical questions, uniform sentence length modification, or heaping of precise numbers.

R4 Stylistic Boundaries

P15 Dramaturgical Frame Requires Explicit Request 〔Convention〕

Classroom personas ("Materials distributed," "Lecture begins," "Specimen museum"), theatrical asides, interview frames, suspenseful previews ("Pause—"). Only activate when the user explicitly requests them. Default to plain exposition.

P16 Maximum Meme Lines Quota 〔Convention〕

At most one aphoristic summary per article. Do not use "Takeaway in one line" type closing previews.

P17 Chinese-English Mixed Formatting 〔Engineering〕

Add a space between Chinese and English characters; use full-width punctuation in Chinese context; add a space between numbers and units. Follow the Chinese Copywriting Guidelines (sparanoid/chinese-copywriting-guidelines) for details.

P18 Punctuation and Parentheses 〔Engineering: GB/T 15834—2011, CY/T 154—2017〕

Commentary writing priority: Appositive directly written > parentheses > dashes. Use appositives for commentary that can be read continuously with the main text; use parentheses for side notes that don't need continuous reading; dash-separated commentary is part of the main text and needs continuous reading—use sparingly in Chinese technical writing (high dash density is also an empirical fingerprint of AI writing).

• Appositive (preferred): First use the repository's built-in resource packaging script build_assets.py to package, then run.
• Parentheses (side note): Supports batch export (requires admin permissions).
• Dash (continuous commentary, use sparingly): If truly needed, use a two-character dash —, occupying two character positions without breaking, usually with no punctuation before it.

Parentheses width (full-width vs half-width) is determined by content and adjacent environment; maintain consistent style throughout the entire document (CY/T 154 consistency principle):

Scenario	Form	Example
Paired translation "Chinese (English)"	Full-width, no spaces around	消息队列（Message Queue）
Commentary containing Chinese	Full-width, no spaces around	支持批量导出（需要管理员权限）
Pure English, numerals, version references	Half-width, space before	Based on Spring Boot (v3.2.0)
Parentheses adjacent to code or filenames	Half-width, spaces on both sides	Run build.sh (first run downloads dependencies) then restart

Known divergence: Publishing conventions use full-width for "Chinese (English)" (GB/T 15834, Guidelines examples); some engineering specifications use half-width with a space for all pure English content (Gengo). plain-zh defaults to full-width for equivalents, half-width for engineering references; if the project has its own conventions, follow them consistently throughout the document.

Other hard rules:

• No nested parentheses; if nesting is required, use different forms for outer (〔〕) and inner (（）).
• Intra-sentence parentheses immediately follow the annotated word; no period at the end. Extra-sentence parentheses come after the sentence-ending punctuation.
• Quotation marks: Simplified Chinese defaults to " "; nested ' '. Corner brackets 「」 『』 for Traditional Chinese or when the project convention uses them; consistent throughout.
• Ellipsis uses ……, not three periods.
• Chinese sentences still use dun-comma (、) for English coordinate items (e.g., at the bus stop、at the railway station).
• Parenthetical commentary: no more than 2 per paragraph; continuous side notes should be expanded into the main text.

Exceptions: Half-width parentheses in code blocks and command lines; parentheses in mathematical formulas; compact parentheses in tables; existing document typographic conventions.

R5 Rewriting Discipline (Review Mode Only)

P19 Minimum Change

Only change what is necessary to fix the issue; do not polish adjacent text. The more you change, the more opportunities you create for new errors. When in doubt, keep the original.

P20 Information Conservation

Preserve facts, numbers, qualifiers, attributions, and negation scope completely. Do not change "possibly" to "certainly" or "planned" to "completed." Every content word added in the rewrite must be traceable to a source in the original text.

P21 Structural Stability

Preserve heading levels, chapter order, paragraph order, and the positions of lists, tables, references, and code blocks. Before changing a heading, check all cross-references and anchors.

P22 Post-Rewrite Self-Check

Go through each item: Do added content words have sources? Are all terms defined or contrasted at first appearance (P1-P3)? Are interface terms contrasted (P3)? Are headings metaphor-free (P4)? Are undefined abbreviations within quota (P6)? Have rebuttal framing and prompt colons been handled or justified for retention (P8-P9)? Are enumeration and compression density within limits, and free of counting collective terms (P13)? Are punctuation and parentheses compliant, with appositives prioritized for commentary (P18)? Is the dramaturgical frame inactive or user-requested (P15)?

Three-Layer Judgment Division

• Countable indicators (abbreviation count, metaphor density, same-term rotation, dash density): Can be scripted; this project reserves a detect interface.
• Sentence-level judgment (whether the hit is valid, whether the exception boundary applies): Model judges according to this document's closed criteria, marking uncertain ones as "Pending Review."
• Metaphor appropriateness: Only list candidates; user decides; model does not evaluate.

Review Mode Workflow

1. Read through the full text; determine genre and audience; list claims, data, and limitations that should be preserved.
2. Check point by point against P1-P18. For each hit, record: rule number, original sentence location, modification method, and judgment (To Modify / Preserve / False Positive / Pending Review). A "preserve" judgment must include a specific reason, not just "it reads naturally."
3. Generate a report: Group hits by R1-R4 (original sentence, modification method, judgment); provide statistics by category (terminology / structure / style). Only ask the user to reply "Apply changes" or suggest adjustments to the entire set; do not request approval for each individual item.
4. After receiving confirmation, rewrite following P19-P21. Record each change as "original, modified, rule hit number."
5. After rewriting, perform P22 self-check. Output a before-and-after comparison (using strikethrough for original and insertion marks for new), and verify that all "To Modify" items have been resolved.

Pre-Delivery Checklist

• Each term defined or given an equivalent at first appearance (P1, P3).
• One concept, one name (P2).
• Headings metaphor-free (P4).
• Undefined abbreviations within quota (P6).
• Rebuttal framing and prompt colons handled or justified for retention (P8, P9).
• Dramaturgical frame inactive or user-requested (P15).
• Enumeration and coordination within limits, no counting collective terms (P13).
• Facts, qualifiers, and structure unchanged (P19-P21).
• X-level features not mistakenly altered.

Sources

• lieflat-less-ai-tone: All R3 criteria and X-level list (629 comparison documents + 270 paired retests).
• Fenng/Tech-Doc-Style-Chinese: ASD-STE100 controlled writing approach (P2, P3).
• francoisdp/skills (anti-ai-writing): Dual-mode architecture and Rule 25 "define before use" (P1).
• op7418/Humanizer-zh: Three-part preservation boundary and information conservation (R5).
• sparanoid/chinese-copywriting-guidelines: Mixed-formatting rules (P17).
• GB/T 15834—2011 "Punctuation Usage" and CY/T 154—2017 "Editorial Rules for English in Chinese Publications": Punctuation forms and style consistency principle (P18).
• Gengo Chinese Style Guide: Engineering rule for parentheses width based on content (P18).
• cloudflare-docs eli5 skill: Analogies and failure boundaries (P7).
• opencue/cuecards ai-slop-detector: Cognitive load basis for undefined abbreviations (P6).

License

MIT