Home

STE-Linter

A writing linter for technical documentation, in the spirit of ASD-STE100 Simplified Technical English.

A spell-checker asks whether a word is a word. STE-Linter asks whether a sentence can be misread by someone who has to act on it.

It reads Markdown and CSV and reports the words and sentence shapes that make technical writing imprecise. Hedges that let a rule mean anything. References with no antecedent. Sentences carrying three demands at once. Filler that survives deletion without loss.

Stdlib-only Python, 3.9 and up. No dependencies, no build step, no network access.

---

Start here

If you want to	Read
Get it running in under a minute	Installation
Know what every flag does	CLI Reference
Understand what the standard actually is	Simplified Technical English
Understand how a finding gets produced	How the Linter Works
Tune the rules for your repository	Configuration
Let Claude lint and rewrite your prose	Agent Skill
Wire it into CI, pre-commit, VS Code or HELVE	Integrations
Send a patch	Contributing

---

The six tests

Every finding belongs to one of six tests. Each asks a different question about a sentence.

Test	Question it asks	Fires on
T1 Replaceable	Is there a shorter, plainer word for this?	utilize, in order to, facilitate
T2 Unfalsifiable	Could anyone prove this claim false?	robust, appropriate, user-friendly
T3 Optional	Does this leave the reader a choice you did not mean to give?	should, may, as required
T4 Referentially open	Does every reference have exactly one antecedent?	It, this, faster with no baseline
T5 Non-atomic	Does this sentence make exactly one demand?	two shalls, and/or, chained and
T6 Zero-information	Does deleting this change the meaning?	filler, weasel words, AI tells

Alongside those sit structural checks (passive voice, TBD), word and sentence budgets, and CSV registry integrity checks. The full catalogue, with worked before/after rewrites, is in docs/rules.md.

---

Three ways to run it

Command line — for humans, editors and CI.

pipx install ste100-linter
ste100 docs/

Exit 0 when clean, 1 on error-tier findings, 2 on tool failure. See CLI Reference.

Agent skill — lets Claude lint and rewrite prose before handing work back.

mkdir -p ~/.claude/skills
cp -r .claude/skills/ste100-lint ~/.claude/skills/ste100-lint

See Agent Skill.

HELVE tool — newline-delimited JSON-RPC over stdio, for tool hosts.

ste100-helve --helve-rpc

See Integrations.

---

A worked example

Three sentences of ordinary-looking documentation:

# Recovery

The operator should utilize the appropriate procedure to restore the system
as required. It is important to note that the system will handle errors and
the controller shall reset the link and it shall log the event.

All six tests fire. Real output, with only the indented source-snippet line under each finding removed for length:

$ ste100 --profile spec guide.md
ste100: 1 files, 9 errors, 4 warnings, 1 review
smell_density=6.5 ari_grade=10.66 passive_ratio=0.0 budget_violations=0
guide.md:3:14 ERROR T3 STE-T3-HDG-0106 -- Optional (hedge): 'should'.
guide.md:3:21 ERROR T1 STE-T1-SUB-0104 -- Replaceable: 'utilize' -> 'use'.
guide.md:3:33 ERROR T1 STE-T1-SUB-0233 -- Replaceable: 'appropriate' -> 'proper'.
guide.md:3:33 WARNING T2 STE-T2-VAG-0015 -- Unfalsifiable: 'appropriate' with no number, unit, or named acceptance condition.
guide.md:4:1 ERROR T3 STE-T3-ESC-0006 -- Optional (escape clause): 'as required'.
guide.md:4:14 ERROR T1 STE-T1-SUB-0328 -- Replaceable: 'It is' -> ''.
guide.md:4:14 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'It' with no clear antecedent in this unit.
guide.md:4:14 ERROR T5 STE-T5-MULTI-0001 -- Non-atomic: 2 'shall' imperatives in one sentence.
guide.md:4:14 ERROR T6 STE-T6-AI-0004 -- Zero-information (AI tell, hedging_opener): 'It is important to note that'.
guide.md:4:38 WARNING T4 STE-T4-PRO-0017 -- Referentially open: pronoun 'that' with no clear antecedent in this unit.
guide.md:4:54 ERROR T3 STE-T3-HDG-0143 -- Optional (hedge): 'will'.
guide.md:5:37 ERROR T5 STE-T5-COMB-0001 -- Non-atomic: second combinator 'and' in one sentence (spec profile).
guide.md:5:41 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'it' with no clear antecedent in this unit.

---

What this is not

This project is inspired by ASD-STE100 and is not a licensed, certified, or conforming implementation of it. It ships no part of the ASD STE Dictionary and makes no conformance claim. The rule tables are independently assembled from open sources, and a clean run here does not mean a document meets the standard.

For the standard itself, see asd-ste100.org and the Simplified Technical English page, which explains what the specification contains, how to obtain it, and where this tool departs from it.

It is also not a grammar checker and not a style guide. It will not catch a factual error or an awkward paragraph. It catches a bounded, well-defined set of ambiguity patterns and stays quiet about everything else.

---

Status

Beta. The rules and CLI are stable enough to use daily, and rule IDs are stable from v0.1.0 onward. Read the known limitations before adopting it in blocking CI — in particular, the shipped default preset's tuning for ordinary documentation applies to a fixed list of paths, which is tracked in issue #8.