paultyng Simplify Prose
Rewrite or check reader-facing technical text with the mechanical core of ASD-STE100 Simplified Technical English (STE), the controlled language aerospace and defense manufacturers use for maintenance manuals. The rules exist so a tired reader who is not a native English speaker cannot misread an instruction. They remove the usual signs of AI slop as a side effect: long sentences, synonym rotation, hedges, filler, decorative clauses.
Write for that tired reader. Each sentence must survive one read.
Scope: where this skill applies
Scope-split with the terse-output rule:
- This skill owns reader-facing technical text (docs, READMEs, runbooks, error messages, release notes, incident reports, agent/system prompts). Keep complete grammar — articles, "that", no telegraph style, no contractions — for non-native readers.
terse-outputowns chat replies, PR/review comments, commit messages, where aggressive word-dropping is right.match-voiceowns marketing, brand, and personal-voice writing. Do not apply this skill there; STE deletes persuasion by design (see Limit).
The modal ladder, slop substitutions, and condition-before-command are shared with terse-output. The completeness rules (keep articles, keep "that", no contractions) are this skill's alone.
Workflow
- Classify each passage as procedural or descriptive. Every other rule depends on this.
- Fix vocabulary before drafting. Pick ONE verb for the check/verify/confirm concept and ONE noun for the config/settings concept. Use no other word for these concepts in the whole document.
- Apply the core rules (below).
- Leave untouchables exact — code, identifiers, commands, quoted errors.
- Run the self-check before delivering. Not optional.
When asked to CHECK text instead of writing it, report each violation as: the offending text, the problem, a compliant rewrite. Use references/checklist.md for the searchable pass.
Classify first
| Procedural (instructions) | Descriptive (explanations) | |
|---|---|---|
| Purpose | Tell the reader what to do | Explain what a thing is or does |
| Verb form | Imperative: "Install the pump." | Simple present / past / future |
| Sentence cap | 20 words | 25 words |
| Unit rule | One instruction per sentence | One topic per paragraph, max six sentences |
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 cap, no imperative).
Core rules
Sentence caps. 20 words procedural, 25 descriptive. Backticked code, identifiers, numbers-with-units, and quoted text each count as one word toward the cap — long identifiers do not blow the budget. Over the cap → split into two sentences.
Simple tenses only. Use infinitive, imperative, simple present, simple past, simple future, and past participle as adjective ("the cached response"). No present perfect ("has completed" → "completed"). No -ing verb forms — an -ing word is legal only as a noun ("logging") or inside one, never as a verb ("making it easy" → new sentence).
Active voice. Passive is legal only in descriptive text when the agent is genuinely unknown.
Modal ladder. Approved: can, will, must. Replace should/would/may/might/could — see references/substitutions.md. UPPERCASE RFC 2119 key words (MUST/SHOULD/MAY) are exempt: they are deliberate normative terms, not hedges (see the normative-language rule).
Condition before command. Lead with the condition, comma, then the action: "increase the timeout if the network is slow" → "if the network is slow, increase the timeout."
Complete grammar. This is the anti-terseness rule and the line against telegraph style. Keep articles (the/a/an), keep "that" after "make sure", expand contractions. STE is short sentences with full grammar, not telegram: "Ensure file exists before running" → "Make sure that the file exists before you run the command."
One word, one meaning. Pick one term per concept and hold it for the whole document. Collapse rotations: check/verify/confirm/validate → one; config/settings/options → one; run/execute/invoke → one. See references/substitutions.md.
Slop → plain. Delete or replace filler that carries no fact (leverage, utilize, robust, seamlessly, "in order to", "it is worth noting"). Full table in references/substitutions.md.
Warnings first. For a destructive action, put the command or condition first, then the risk: "Do not run --force against production. The flag deletes rows that do not match the source."
No semicolons. Write two sentences instead. Use a vertical list for more than two items or steps.
Untouchables
Leave these exact, even when they break a vocabulary rule:
- Code blocks, inline code, identifiers, CLI commands, flags, file paths
- Quoted error messages and log lines
- Product names, API endpoint names, config keys
- Numbers with units (each counts as one word)
Self-check before delivering
Not optional. Run these on the draft:
- Count words in the three longest sentences. Over 20 (procedural) / 25 (descriptive) → split.
- Search for:
'll're's-contraction,has been,have been,should,, making/, allowing/, ensuring, semicolons. Fix each. - Search every
ifandwhen. Each must stand at the START of its sentence, before the command, with a comma. - Search for the check/verify/confirm verbs you did NOT pick. Replace every hit with your chosen verb.
For a full audit, run references/checklist.md.
Full example
Before (real AI output, ~40-word sentences, rotating verbs):
If sqlpipe hangs or fails with
dial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a firewall rule blocking the connection. If you're connecting to a managed database (RDS, etc.), confirm the instance allows connections from sqlpipe's IP.
After (procedural, verb = "make sure", conditions first, one instruction per sentence):
sqlpipe stops with
dial tcp: i/o timeoutwhen it cannot reach the Postgres port (5432 by default).
- Make sure that the host that runs sqlpipe can reach the Postgres port. A firewall or security group usually blocks it.
- If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.
Changed: sentences split under 20 words; "you're" expanded; "check"/"confirm" collapsed to "make sure that"; conditions moved before commands; "etc." removed; code and error strings untouched.
Limit
STE is for technical facts and instructions. Do not apply it to marketing copy, blog voice, or personal-voice writing — it deletes persuasion by design. When asked to simplify such text, say so and hand off to match-voice, or offer STE for the docs instead.
This skill is an unofficial aid. It is not affiliated with or endorsed by ASD or STEMG, and no tool can guarantee STE compliance. ASD-STE100 is a registered trademark of ASD. The official standard is a free download at asd-ste100.org.
References
references/checklist.md— searchable verification pass for check mode and final auditsreferences/substitutions.md— modal ladder, slop → plain table, one-word-one-meaning consistency sets
Sources
Rules and examples adapted from the SimpleEnglish skill by AminBlg, used under the MIT License (Copyright (c) 2026 AminBlg). SimpleEnglish paraphrases ASD-STE100 Issue 9; the official standard (with the ~900-word approved dictionary, not reproduced here) is a free download at asd-ste100.org.