STE-Rewrite

---
name: ste-rewrite
description: Rewrite prose into ASD-STE100 Simplified Technical English with controlled vocabulary, plain syntax and punctuation, and measured readability scores. Removes AI slop patterns (contrastive reframing, dramatic pivots, empty emphasis, clichéd vocabulary). Use when the user asks for plain language, a rewrite of dense or AI-generated prose, or text that must follow a controlled standard. Triggers on "simplify", "make clearer", "STE", "controlled English", "remove AI slop", "de-slop", or requests to strip opinion from prose.
---

# ASD-STE100 Rewrite

Rewrite prose to follow ASD-STE100 principles: one meaning per word, short sentences,
no opinion or commentary. Measure every rewrite with the `readability-analysis` skill
so the improvement shows in numbers, not assertion.

## When to use

- The user asks to simplify, clarify, or rewrite dense or bureaucratic prose.
- The user references STE, ASD-STE100, controlled English, or plain language.
- The user wants subjective opinion, marketing language, or hedging removed from a document.
- Before finalizing any SOP, policy, incident report, or technical procedure.

## When not to use

- The user wants a readability *report* only (use `readability-analysis` directly).
- The user wants marketing copy, persuasive writing, or creative prose.

## Core rewrite rules

Follow these rules in order. Each rule cites the ASD-STE100 principle it derives from.

### 1. Strip subjective content (STE Section 1)

Remove all opinion, evaluation, and unverifiable claims. Rewrite each to state only
what can be observed or measured.

| Subjective (rewrite) | Objective (keep) |
| ---------------------- | ------------------- |
| "This is the best approach" | "This approach meets 8 of 10 requirements" |
| "The system is very slow" | "The system takes 45 seconds to respond" |
| "It is important to note that" | (delete; state the fact directly) |
| "We believe this will help" | "This change reduces error rate by 12%" |

Delete hedging phrases: "it seems", "it appears", "arguably", "hopefully", "in our
opinion", "to some extent", "quite", "rather", "very" (when it modifies a measurable
property).

### 2. One meaning per word (STE Section 2)

Use each approved word for one meaning only. If a word has two dictionary meanings,
pick the one that matches the STE approved definition and use a different word for the
other meaning.

| Ambiguous word | STE-preferred replacement |
| ---------------- | --------------------------- |
| "check" (verb: verify / inspect / test) | "verify", "inspect", or "test" |
| "run" (verb: operate / execute / manage) | "operate", "execute", or "manage" |
| "follow" (comply / come after / understand) | "obey", "come after", or "understand" |
| "address" (speak to / deal with / location) | "speak to", "resolve", or "location" |

### 3. Short sentences (STE Section 4)

- Descriptive text: maximum 25 words per sentence.
- Instructions / warnings: maximum 20 words per sentence.
- Split any sentence that contains two or more independent clauses joined by "and",
  "but", "or", or a semicolon. Give each clause its own sentence.

### 4. Active voice, imperative for procedures (STE Section 4)

- Descriptive text: active voice. "The valve controls flow", not "Flow is controlled
  by the valve."
- Instructions: imperative mood. "Open the valve", not "The valve should be opened."
- Name the agent when the actor matters: "The operator opens the valve", not "The
  valve is opened."

### 5. One topic per paragraph (STE Section 4)

Each paragraph covers one topic. If a paragraph mixes procedure with background, split
it. Keep paragraphs to 6 sentences or fewer.

### 6. Approved connectives (STE Section 4)

Use only these words to connect clauses and sentences:

- Addition: and, also, in addition
- Contrast: but, however, although
- Cause: because, since, as
- Result: so, therefore, thus
- Condition: if, unless, when
- Time: before, after, during, while, until

Delete: "moreover", "furthermore", "nevertheless", "notwithstanding", "henceforth",
"whereupon", "inasmuch as".

### 7. Noun phrases (STE Section 2)

Keep noun phrases to 3 words or fewer. Break longer chains into separate words:

| Long chain | Rewrite |
| ------------ | --------- |
| "system error log file" | "the log file for system errors" |
| "user account access control list" | "the access control list for the user account" |

### 8. Verb forms (STE Section 2)

Use only these verb forms:

- Infinitive: to write, to open
- Present tense: writes, opens
- Past tense: wrote, opened
- Past participle as adjective: written procedure, opened valve
- Gerund as noun: writing, opening

Do not use future tense ("will open") in procedures. Use present tense ("opens") or
imperative ("open").

### 9. Plain punctuation (STE Section 4)

Punctuation carries no meaning on its own. Use the simplest mark that ends or separates
the thought.

- End sentences with a period. This is the default mark.
- Replace every em dash with a period (start a new sentence) or a comma (short aside).
- Replace every semicolon with a period. Give each clause its own sentence.
- Use a colon only to introduce a list or an example.
- Keep parentheses rare: one pair per paragraph at most, never nested. Move the aside
  into its own sentence.
- Remove exclamation marks from technical prose.
- Remove decorative Unicode: curly quotes used for emphasis, bold or italic that does
  not mark a genuine warning or term, mid-prose emoji.

### 10. Remove AI slop patterns

STE controls words. These patterns control structure, and they signal generated text
while adding no information. The full checklist lives in
`references/ai-slop-tells.md`. The table below covers the patterns that appear most
often.

| Pattern | Example | Rewrite |
| --------- | --------- | --------- |
| Contrastive reframing | "It's not X, it's Y" | State Y directly. Delete the negation of a claim nobody made. Exception: if X and Y are each a distinct, supported claim (e.g. "X is necessary but not sufficient"), keep both; convert a genuine enumeration into a list instead of deleting it. |
| Dramatic pivot | "But here's the thing." / "That's where X comes in." | Delete the pivot sentence. Start the next sentence with the fact. |
| Vapid opener | "In today's fast-paced world," / "Let's dive in" | Delete. Start with the subject of the document. |
| Empty emphasis | "Importantly," / "Notably," / "It goes without saying" | Delete the marker. If the point matters, state why in plain words. |
| Snappy triad | "robust, scalable, and secure" | Keep the one accurate claim and quantify it. |
| False balance | "While X is true, Y is equally important" | State X and Y as separate claims, each with its evidence. |
| Closing cliché | "In conclusion," / "The bottom line is" / "Only time will tell" | Stop writing when the content ends. |
| Sycophancy | "Great question!" / "You raise an excellent point." | Answer the question. |
| Hallucinated authority | "Studies show..." / "Experts agree..." | Cite the specific source or delete the claim. |
| Metaphor cliché | "a tapestry of" / "the backbone of" / "a double-edged sword" | Name the thing literally. |
| Business jargon | "leverage" / "move the needle" / "circle back" | Use the plain verb: "use", "change", "reply". |
| Intensity filler | "truly" / "now more than ever" / "countless" | Delete, or replace with a measurement. |
| Mid-sentence question | "The solution? It's simple." | State the answer: "The solution is simple." |

### Slop vocabulary

These words appear often in generated text, but frequency and combination are the
signal, not any single instance -- one occurrence does not by itself mark a passage
as generated. Substitute the plain word when the broader context supports it.

| Avoid | Use instead |
| ------- | ------------- |
| delve, dive into | examine, study, read |
| leverage | use |
| seamless, robust, holistic | (delete, or state the measured property) |
| comprehensive, definitive, ultimate | (delete, or state the scope) |
| streamline, optimize | simplify, speed up, or the specific change |
| empower, enable, unlock | let, allow, or the specific capability |
| journey, landscape, realm, tapestry, ecosystem | the literal subject |
| foster, cultivate, nurture | build, grow, support |
| cutting-edge, game-changing, revolutionary | (delete, or state what changed) |
| crucial, vital, pivotal, paramount | (delete, or state the consequence) |

## How to run a rewrite

### Step 1: Measure the source

Run the readability script on the original text:

```bash
uv run .claude/skills/readability-analysis/scripts/analyze_readability.py <file.md>
```

Use `uv run` exactly as shown — the script's dependencies are inline PEP 723
metadata, which `python3 <script>` does not read.

Record: Flesch Reading Ease, Flesch-Kincaid grade, Gunning Fog, SMOG, words/sentence.
This is the baseline. Do not skip this step.

### Step 2: Rewrite sentence by sentence

Work through the flagged-sentence list from worst to best. For each sentence:

1. Identify the core assertion (what does it claim?).
2. Strip subjective modifiers and hedging.
3. Check the sentence against the slop-pattern table (rule 10). Delete or rewrite
   every match.
4. Check each word against the controlled-vocabulary and slop-vocabulary tables.
5. Fix the punctuation against rule 9.
6. Split if longer than 25 words (descriptive) or 20 words (procedural).
7. Convert passive to active. Convert descriptive to imperative if it is a step.
8. Verify the sentence still conveys the original meaning.

### Step 3: Re-measure

Run the readability script on the rewrite. Compare against the baseline.

### Step 4: Report

Present results in this order:

1. A compact before/after metrics table.
2. The rewritten text.
3. A list of words, phrases, and slop patterns flagged as non-compliant, with the
   rule number and reason for each flag.

Example report format:

```markdown
## Metrics

| Metric | Before | After |
| -------- | -------- | ------- |
| Flesch Reading Ease | 28.3 | 52.1 |
| Flesch-Kincaid Grade | 14.2 | 9.8 |
| Gunning Fog | 16.1 | 11.4 |
| SMOG | 13.7 | 10.2 |
| Words per sentence | 32.1 | 18.4 |

## Rewritten text

[rewritten text here]

## STE compliance flags

| Word/Phrase | Rule | Reason |
| ------------- | ------ | -------- |
| "very slow" | Subjective | Unmeasurable; replaced with measured time |
| "utilize" | Vocabulary | Not in approved dictionary; use "use" |
| "system error log file" | Noun phrase | 4-word chain; split with preposition |
```

## Controlled vocabulary quick reference

These are the most common substitutions. The full ASD-STE100 dictionary has about
900 approved words. Use the nearest approved synonym when a word is not listed.

| Avoid | Use instead |
| ------- | ------------- |
| utilize | use |
| commence | start |
| terminate | stop, end |
| approximately | about, approximately (if precision matters) |
| sufficient | enough |
| prior to | before |
| subsequent to | after |
| in the event that | if |
| in order to | to |
| due to the fact that | because |
| at this point in time | now |
| a large number of | many |
| is able to | can |
| has the capability to | can |
| perform an analysis | analyze |
| make a decision | decide |
| take into consideration | consider |

## Common mistakes

- Rewriting so aggressively that the technical meaning changes. Keep domain terms.
  Simplify structure, not concepts.
- Deleting warnings or cautions to hit a word count. Warnings stay. Reword them.
- Treating STE rules as absolute when they conflict with safety or legal requirements.
  Safety and legal text overrides style rules.
- Reporting "the text reads better" without metrics. Always cite the numbers.
- Swapping slop words but keeping slop structures. Replace the whole "not X but Y"
  frame with a direct claim, not just the adjectives inside it.
- Fixing punctuation cosmetically. An em dash removed from a slop sentence still
  leaves a slop sentence. Apply the structural rules first.