Hai Simplified Technical

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Make a technical document readable in one way only: one word for one concept, one topic in one sentence, a named actor for each action, and a fixed set of words for requirements. The rules come from the nine sections of ASD-STE100 Part 1. The English rules keep the STE grammar rules that matter for software text. The Chinese rules drop the English-only grammar and add the faults of Chinese technical writing: hidden verbs (进行, 加以), long pre-noun modifiers, missing subjects, unclear pronouns.

Both languages share one rule numbering. references/rules-en.md and references/rules-zh.md hold the full rules with reasons, examples and checks.

Scope

Technical documents only: text that a reader uses to understand a system, do an operation or make a technical decision. Design docs, READMEs, API references, runbooks, troubleshooting and migration guides, commit messages, PR descriptions, code comments, error messages and UI help text are in scope.

Not marketing or creative text: marketing copy, brand stories, blog and social posts, launch announcements, speeches, fiction. That text works through rhythm, emotion and rhetoric. These rules make it flat and defeat its purpose. Write it normally and do not apply this skill.

Mixed documents: release notes and announcements often mix promotion and technical content. Apply the rules to the technical parts only (what changed, how to upgrade, what breaks).

If the user explicitly asks for these rules on non-technical text, do it, and say once that the text will lose its persuasive tone.

Language

• Write each part in the rules of its own language. Detect the language from the document, not from the conversation.
• A Chinese document with English terms uses the Chinese rules; 9.1 decides how the terms appear.
• A bilingual document applies each language's rules to its own text.
• A translation is not part of this skill. When the user asks for one, translate first, then apply the rules of the target language.

Workflow

1. Check the scope. Confirm that the text is technical (see Scope).
2. Find the project conventions. Look for a glossary and a style guide (section 10 of the rule files says where). Project conventions win over these rules, for example a quotation style or a fixed translation.
3. Write or rewrite. Follow the summary below. Open the rule file of the language when a rule is unclear or when you need an example.
4. Run the mechanical check. python3 <skill dir>/scripts/check.py <file> (add --lang en or --lang zh to force one language). It lists places to look at, not verdicts: quoted examples, names next to code, and soft rules kept for a reason can stay.
5. Deliver. Follow references/output-template.md.

Rule summary

Obey every hard rule. Obey about 80% of the soft rules, and have a reason for each one you break.

1 Words

• 1.1 hard: One word for one concept. Do not vary words for style.
• 1.2 hard: One meaning for each word.
• 1.3 hard: Use the glossary. Name a new concept before you use it.
• 1.4 hard: No vague words. EN: appropriate, relevant, various, significant, fairly, basically. ZH: 适当、有关的、一定程度上、较为、基本上、若干、显著、大幅、明显. Give a number, a name or a condition.
• 1.5 soft: Verbs that say what happens. EN: handle, process, manage, optimize. ZH: 处理、操作、支持、优化、调整.

2 Noun phrases

• 2.1 soft: At most two modifiers before a noun. ZH: at most two 的.
• 2.2 soft: At most three nouns together.
• 2.3 hard: Modifier markers. EN: hyphenate a compound modifier before a noun. ZH: use 的/地/得 correctly.

3 Verbs

• 3.1 hard: Do not hide the verb in a noun. EN: perform, carry out, conduct, make an adjustment. ZH: 进行、加以、予以、做出、实现了对……的.
• 3.2 soft: Active voice; name the actor. EN: passive. ZH: 被, 由……做.
• 3.3 soft: State facts in the simple tense. EN: no "is sending". ZH: no 正在, no 着 for state.
• 3.4 hard: Fixed requirement words. EN: must / must not / should / should not / can / need not (or the project's RFC 2119 words). ZH: 应 / 不应 / 宜 / 不宜 / 可 / 不必.
• 3.5 soft, EN only: A one-word verb when one exists ("find", not "find out").

4 Sentences

• 4.1 hard: One topic in each sentence.
• 4.2 hard: Name the actor. EN: no empty "It is / There is", no dangling modifiers. ZH: write the subject when it changes.
• 4.3 hard: Each pronoun points to one thing. EN: no bare "this". ZH: 它、这、该、其.
• 4.4 soft: Show the connection: because, so, if, but / 因为、所以、如果、但.
• 4.5 soft: A vertical list for three or more items.
• 4.6 hard, EN only: Do not leave out articles or "that" (no telegraph style).

5 Procedures

• 5.1 hard: Numbered list, one instruction in each step.
• 5.2 hard: Start each step with an imperative verb.
• 5.3 hard: Condition before instruction ("If X, do Y").
• 5.4 soft: Step sentences at most 20 words (EN) or 40 characters (ZH).
• 5.5 soft: Reasons before the list; each result after its step.

6 Descriptive writing

• 6.1 hard: Conclusion first in each paragraph.
• 6.2 soft: One topic in each paragraph, at most six sentences.
• 6.3 soft: Descriptive sentences at most 25 words (EN) or 50 characters (ZH).
• 6.4 hard: Every measured number has its conditions and date.
• 6.5 hard: Keep what is done apart from what is planned.

7 Warnings

• 7.1 hard: A warning comes before the step it applies to.
• 7.2 hard: The instruction first, then the risk.
• 7.3 soft: One risk in each warning.
• 7.4 hard: Two levels. Warning / 警告: data loss, irreversible, wrong without an error, production impact, publishing outside. Caution / 注意: slower, rework, long wait.

8 Punctuation, numbers, length

• 8.1 hard: EN: ASCII punctuation. ZH: full-width punctuation.
• 8.2 hard: One quotation style in each document.
• 8.3 hard: EN: a space between number and unit. ZH: a space between Chinese and Latin letters or digits.
• 8.6 hard: Ranges with "–" (or "to" / "到"), never "~".
• 8.7 hard: Dates that cannot be misread; ISO in tables and parentheses.
• 8.8 hard: Count EN words between spaces; count ZH characters, plus one for each Latin word, number or code span.

9 Writing practices

• 9.1 hard: One form for each term. EN: one spelling and case. ZH: the original or one fixed translation.
• 9.2 hard: Code names in backticks, exactly as in the code.
• 9.3 hard: Official product names; abbreviations defined at first use.
• 9.4 soft: No idioms, filler or marketing words. EN: seamless, leverage, simply, just, easily. ZH: 开箱即用、无缝、一劳永逸、赋能.
• 9.7 soft, EN only: No contractions; no e.g., i.e., etc., via.

Do not overdo it

The rules make the reader understand one meaning. They do not make the text a telegram.

• The 80% has limits. Keep every hard rule. Break a soft rule when obeying it would make the sentence awkward or lose information; each rule gives its reason, and where the reason does not apply, the rule need not either.
• The rules control wording, not content. Keep every fact, condition, exception and doubt of the original. If the original misses something the reader needs (a risk, a rollback, a stale cache), still say so, as a note or an open question. Do not drop domain judgment to look plain.
• Rewriting is not auditing. Keep each claim of the author at the strength it was written; remove only the empty intensifier ("improved significantly" → "improved", "various other services" → "other services"). Do not ask the document to prove its claims inline. List the missing evidence for the author in the report instead (references/output-template.md).
• Inline placeholders are rare. Write "[TBD: …]" / "[待补：……]" in the document only when the reader cannot do the task without the fact (which flag to set, which key to check). Never put a guess in a placeholder, and never write a plausible number.
• Do not touch what must stay. Quotations, code, command output, proper names and the user's own words stay as they are.
• Keep the structure. Reorder sentences, but keep sections, headings and links unless the user asks for more.

Use a different skill when

• The document's content is out of date and must be rebuilt from verified conclusions — use hai-rewrite-doc, then apply this skill to the wording if the user wants it.
• The question is whether the document is true or consistent with the code — use hai-audit-docs.
• Only the Markdown layout is wrong — use readme-beautifier.
• The question is what to call a concept across modules — use hai-naming; record the result in the glossary.
• The task is to write or shape a PRD — use hai-prd. This skill can polish its wording later.

Common mistakes

• Applying the rules to marketing copy and making it flat.
• Turning every unmeasured claim into an inline "[TBD]": the document becomes a checklist of gaps. Report the gaps to the author; keep the document readable.
• Putting a guessed value in a placeholder, or writing a plausible number.
• Removing a caveat or a risk because the sentence got shorter without it.
• Changing a correct technical term to obey 1.4 or 9.4.
• Reporting every soft-rule hit of the script as a defect.