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.

Strict extras: follow means come after, never obey. above and below mean physical position only. help is a verb (noun becomes aid). If the possessive is unsure, write "the file of the user". Write but for however, because for causal since, do for perform, prevent for avoid, do again for repeat. Name the target instead of "the example below". Replace a phrasal verb with a one-word verb when a one-word verb exists (Rule 9.3).

Modal ladder (Rule 3.2):

Consistency pass (Rules 1.11, 9.4): collapse synonym rotations to one term. Pick ONE and keep it: config/configuration/settings/options. Pick ONE: check/verify/confirm/ensure (strict: "make sure that"). Pick ONE: run/execute/operate.

7. Delivery

Write only the requested text. No preamble, no summary, no closing remarks unless the user asked for commentary.

Beyond documentation

Same rules, different targets. Full adaptations in references/use-cases.md:

• Error messages: state what happened (simple past), the cause if known, then the fix as an imperative. No "Oops", no "Please ensure", no apology filler: "Connection to the database failed. The password for user app was not correct. Set DB_PASSWORD and connect again."
• Runbooks: STE's home turf. Imperative steps, conditions first, warnings before the step.
• Incident reports: simple past only. "Between 14:02 and 14:31 UTC, 12% of requests failed", not "We have identified an issue that may have impacted..."
• Release notes: breaking changes follow the warning pattern, command first, risk second.
• Agent instructions (prompts, AGENTS.md): a system prompt is a procedure for a reader that cannot ask questions. One instruction per sentence, no "should", condition first. Models read "should" as optional.
• Translation prep: STE's original job. One meaning per word plus complete grammar removes most translation ambiguity.

Workflow

1. Identify genre (README, PR, error, procedure, API note) and pick strict or STE-flavored.
2. Classify each passage as procedural or descriptive; keep the two unmixed.
3. Draft or rewrite under the rules above. In strict mode, pick your one check-verb and one config-noun before drafting (consistency pass).
4. Self-lint (below), then run the script when the draft is non-trivial:

# From this skill directory (repo or install):
python3 scripts/voice_lint.py path/to/draft.md
python3 scripts/voice_lint.py < draft.md

# Install path (if installed under writing/):
python3 ~/.hermes/skills/writing/simple-english/scripts/voice_lint.py path/to/draft.md

5. Score = findings per 100 words. In strict mode, use the delta as a form signal. In STE-flavored mode, review each finding in context; lower is not automatically better.
6. Return the cleaned prose (and the lint summary only if the user wants it). For a full audit, run the verification checklist: references/checklist.md in check mode.

The script (renamed from ste_lint.py; the tool is a generic voice_lint, not STE-locked; the canonical script lives in ~/.hermes/skills/user-profile/writing-voice/scripts/voice_lint.py and is mirrored here for standalone use) also returns two report-only dicts that never count toward the score:

• rhythm: staccato stacks, negation-fragment tails, and paragraph-closing "Not a X." fragments (AI-slop shape tells).
• tells: cliché global openers, conclusion signposts, hedge softeners, AI buzzwords, and "No A. No B. Just C." negation triads.

Findings there are agent judgment cues, not automatic rewrites. The mechanical bans (banned words, marketing adjectives, em dashes, passive voice) are the ones that move the score.

Self-lint (before return)

1. Count words in the three longest sentences. Over 20 (procedural) or 25 (descriptive) — split them.
2. Search for: contractions ('ll, 're, 's), has been/have been, should/would/may/might/could, is being/are being, "-ing" verbs after a comma, semicolons, e.g./i.e./etc..
3. Search for every if and when. Each one stands at the START of its sentence, before the command.
4. Replace em dashes. Procedural text is the forbidden tier. In strict mode, replace semicolons and expand contractions.
5. Does passive voice hide an actor the reader needs? Make that actor active.
6. Same thing named two ways (check vs verify vs ensure; config vs settings)? Pick one.

Mechanical rules can be linted and remove most form-slop. Full STE still needs human judgment (right technical noun, whether a sentence makes sense). This skill fixes form. It cannot make a hollow paragraph true.

Guardrails

• Do not rewrite code, API names, flags, paths, or quoted error strings that must stay literal (they count as one word each under Rule 8.6).
• Do not apply one whole-file score to a mixed README, proposal, or guide. Lint the procedural and technical sections where controlled form fits.
• Do not invent product claims to sound "cleaner".
• Do not split related thoughts or remove a writer's contractions only to lower the score.
• Do not replace an established spelling convention with the package default.
• Do not apply STE voice to fiction, marketing manifesto, or personal essays unless the user insists. When asked for STE on marketing text, say so and offer it for the docs instead.
• Linter is heuristic, not certified STE. Judgment rules of ASD-STE100 need a human. No tool can guarantee compliance; final approval rests with the writer.

Mode examples and mixed-document routing are in references/mode-boundaries.md.

References

• references/checklist.md: verification pass with searchable patterns, for check mode and final audits (added from upstream)
• references/use-cases.md: long-form adaptations — error messages, runbooks, incident reports, commits, UI copy, i18n (added from upstream)
• references/before-after-samples.md: real baseline vs STE examples
• references/experiment-results.md: cross-model headline
• references/experiment-results-openai.md GPT category breakdown
• references/source-and-limits.md: attribution, what the linter does and does not do
• scripts/voice_lint.py: deterministic anti-slop linter

Rule citations reference the ASD-STE100 Issue 9 numbering (as adapted by the upstream Hermes simple-english port); the practical substance is merged here.

Quick contrast