apoapostolov/humanizer/simple-english

Simple English (ASD-STE100)

Write technical prose with ASD-STE100 control. Use full control for procedures, safety text, and errors. Use a lighter clarity pass for reference documentation, PR descriptions, and technical sections inside mixed documents.

Pi register: Worker. Machines and procedures only. README and changelog work bounces to humanizer. Chat with the primary user loads neither skill.

Not for: code, identifiers, command syntax, product voice, essays, personal writing, or any section whose job is to persuade or carry a distinct voice. STE strips voice on purpose.

Unlike writing-prose / humanizer (natural human voice, anti-formula, keep personality): this skill is a controlled writing system with mechanical rules and a measurable linter. Prefer this when the user wants plain technical clarity or "not AI slop" on engineer-facing text. Prefer humanizer when the goal is natural voice in essays, social, or long-form. Prefer sibling ai-writing-detector only for mechanical AI-writing signal scores or rewrite preservation checks. It is not for STE rewrites or authorship proof.

Source kit (episode materials, adapted): woosal1337/blog ep01. Spec: ASD-STE100 Issue 9 (free official standard at https://asd-ste100.org, copyrighted, do not paste the full standard). Additional adaptation from AminBlg/SimpleEnglish and the Hermes optional-skill port optional-skills/creative/simple-english (merged; see monorepo history).

Skill version: 2.4.1 (renamed from plain-english; package ship: apoapostolov/humanizer repository).

When to use

• Make procedures, technical docs, README reference sections, PR text, errors,

or release notes plain and non-sloppy

• Enforce controlled / simplified technical English
• Lint a draft for mechanical slop markers, then rewrite
• User says STE, simplified English, ASD-STE100, or "cure AI slop" on technical

prose

• User names a specific form consumer: error messages, runbooks, incident

reports, release notes, agent instructions, translation prep, UI copy

Modes

Default to STE-flavored for technical prose. Full STE naming (strict mode) means the ASD dictionary rules — in the practical sense, one word one meaning with a fixed check/verify/set/delete vocabulary per document. For a mixed document, apply it only to procedures and technical reference. Route product, editorial, and personal sections to humanizer / writing-prose.

Mode boundary

Strict mode controls form. STE-flavored mode diagnoses friction.

The linter cannot infer mode or intent. A reported item is not an automatic failure in STE-flavored prose.

Classify before drafting

Do not mix the two in one passage. A "Getting started" section is procedural. An "Architecture" section is descriptive. A note inside a procedure is descriptive (25-word limit, no imperative).

Rules

1. Words

• One name for one thing. Do not rename the same item mid-text (Rule 1.11).
• Prefer short common words: start (not begin/commence/initiate), use (not

utilize/leverage), make sure (not ensure), before (not prior to), after (not subsequent to), about (not regarding/concerning), get (not obtain/acquire), show (not demonstrate), also (not additionally/furthermore/moreover).

• Technical nouns and verbs are legal as their own part of speech; never use a

technical noun as a verb ("webhook the event" is wrong; "send the event to the webhook" is right) and never a technical verb as a noun.

• Multi-word technical nouns: three words or fewer; longer chains break with

prepositions ("the timeout value for the connection pool", not "the connection pool timeout configuration value").

• One meaning per word in context. "Fall" means move down, not decrease.
• No marketing adjectives: seamless, robust, powerful, cutting-edge,

effortless, world-class, next-generation, revolutionary, and peers (see linter list).

• Follow the project's established spelling. Default to American spelling only

when the project has no stated or visible convention.

2. Verbs

• Use only: infinitive, imperative, simple present, simple past, simple future,

past participle as adjective. No present perfect, no "is to be installed".

• **Approved modals: can, will, must. Banned: should, would, may, might,

could** (Rule 3.2). "Should" reads as optional to models and tired humans; a requirement becomes "must", a suggestion becomes a fact or is deleted.

• Use an "-ing" form only as a technical noun or inside one ("logging", "the

mounting bracket"), never as a verb. No progressive passive ("is being rebuilt" -> "rebuilds").

• Prefer active voice when the actor matters: "The parser reads the file."

Passive voice stays when the actor is unknown, irrelevant, or less important than the result (Rule 3.6).

• Use a verb for an action. "Analyze the log", not "Perform an analysis of the

log" (Rule 3.7).

• No stacked auxiliaries. Not "it is important to note that this may help to

improve". Write "This improves X".

• Review "-ing" as the main verb. Prefer a simple tense when it is clearer, not

as a mechanical substitution.

3. Sentences

• In strict mode, use one instruction per sentence (Rule 5.2), max 20 words

for instructions and 25 for descriptive sentences (Rules 5.1, 6.3).

• In strict mode, expand contractions and write complete grammar: keep

articles, keep "that". STE is short sentences with complete grammar, not telegraph style. "Make sure that the file exists", not "Ensure file exists" (Rule 4.2).

• In STE-flavored prose, contractions are allowed; keep closely related

thoughts together when splitting creates false crispness or a staccato rhythm.

• Use articles: a, an, the, this, these (Rule 4.5).
• Put a required condition before its command: "If the build fails, read the

log" (Rule 5.4). Search every "if"/"when" — each stands at the START of its sentence, before the command.

4. Punctuation and word count

• No semicolon in strict mode (Rule 8.1). Write two sentences instead.
• No em dash. Procedures, runbooks, errors, and safety text are the

forbidden tier of the house dash rule: they get none, so an instruction is never ambiguous about where a clause ends. Prefer period, comma, colon, or a short new sentence. Avoid en dash as a parenthetical stand-in. Reader-facing technical prose, marketing, and narrative prose have their own tiers; see writing-prose vale/styles/HermesHouse/EmDash.yml. This skill governs procedural text only.

• Parentheses are legal for references, item numbers, abbreviations, plural

forms, explanations, alternatives (Rule 8.3).

• Word counting (Rules 8.4-8.7): in a vertical list the lead-in colon ends

a sentence; text inside parentheses counts as one word; numbers, numbers with units, abbreviations, alphanumeric identifiers, quoted text, titles, labels, proper nouns each count as one word; a hyphenated word counts as one word. So sqlpipe run --config sqlpipe.yaml in backticks counts as one word; long identifiers do not blow the sentence budget.

5. Structure

• In strict mode, one topic per paragraph, at most six sentences (Rules 6.5,

6.6); one new fact per sentence (Rule 6.1).

• For steps, use a numbered vertical list with one action per item.
• A heading must earn at least three sentences of body. Do not put a heading

over a one- or two-sentence stub.

• Define a concept at first use in at most 10 words, one definition per

sentence. Skip product names, standards (Postgres, S3, HTTP), and the tool the doc is about.

• Vertical lists only for three or more parallel items: colon on the lead-in,

uppercase start, one instruction per item.

• If a technical noun needs more than three words, write it in full once, then

a short form or hyphenated units (Rule 2.2).

• Notes give information, never instructions (Rule 5.5). Notes get the

25-word limit.

• Warnings and cautions: command or condition FIRST, risk or result second

(Rules 7.1-7.3). "CAUTION: Do not use the --force flag against production. The flag deletes rows that do not match the source." Never bury the instruction after the explanation.

6. Vocabulary discipline (strict mode) + slop table

The official ASD-STE100 dictionary (~900 approved words, ~1,200 banned with alternatives) is copyrighted and not reproduced here. Its mechanics apply without it: one word, one meaning, one part of speech (Rules 1.1-1.14).

Known part-of-speech rulings that agents break most: test/check/work are nouns ("Do a test", "make sure that X"); run/execute are rejected verbs (use "operate"/"do", or pick one in pragmatic mode); remove is approved; delete/drop as verbs are rejected (use "erase" for data, "remove" for physical); display/ render are rejected (use "show"); ensure/confirm/verify are rejected as verbs (use "make sure that" in strict mode; pick one in pragmatic mode).

If the word carries no fact, delete it instead of replacing it.