/hai-simplified-technical

name: hai-simplified-technical
description: |
  Writes, rewrites and reviews technical documentation in Simplified Technical English (ASD-STE100) or its Chinese adaptation (简化技术中文): one word per concept, short sentences, named actors, no vague words or hidden verbs, imperative steps with the condition first, warnings before the step. Use for design docs, READMEs, API docs, runbooks, migration guides, commit and PR text, code comments and error messages, or when asked for STE, controlled language or plainer docs（按 STE 写、受控中文、写得干净点、去掉翻译腔）. Not for marketing, posts, speeches or fiction. Use hai-rewrite-doc to rebuild content and hai-audit-docs to check facts.

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