[Markdown] Tools for working with agents.

View raw

Table of Contents

--- name: ste-lint description: Lint the prose of Org mode files against Simplified Technical English (ASD-STE100). Use after you write or change text in an Org file, when a project steering file requires STE100, or when the user asks for an STE check of Org notes. ---

STE lint for Org files

Overview

This skill finds Simplified Technical English (ASD-STE100) smells in the prose of Org files. One Elisp file, `ste-lint.el`, holds the rules and the engine. It has two entry points:

The STE rules themselves are in the `ste100` steering module. This skill only checks text. It does not change text.

Usage

Use this skill in these cases:

Lint only the files that you changed. Correct the findings in the lines that you wrote. Do not correct text that the user wrote, unless the user asks.

What the linter checks

The Org parser decides what is prose. The linter checks these parts:

The linter does not check drawers (this includes `:LOGBOOK:` notes), property drawers, planning lines, keywords, tables, comments, source blocks, example blocks, quote blocks, verse blocks, or dynamic blocks.

Inside the prose, the linter masks inline code, verbatim text, timestamps, macros, and link targets. A link with a label keeps only the label. Masked code counts as one word.

The linter applies these rules:

| Severity | Category | Rule | |----------|----------------------|---------------------------------------------------| | ERROR | `contraction` | Do not use contractions. | | ERROR | `latin-abbreviation` | Do not use "e.g.", "i.e.", "etc.", or similar. | | ERROR | `semicolon` | Do not use semicolons in prose. | | WARN | `ampersand` | Write "and", not "&". | | WARN | `slash-conjunction` | Do not write "and/or" or "he/she". | | WARN | `instruction-mood` | Write instructions in the imperative. | | WARN | `nominalization` | Use the verb, not a noun made from the verb. | | WARN | `wordy-phrase` | Use the short word, for example "use" for "utilize". | | WARN | `phrasal-verb` | Use one verb, for example "start" for "kick off". | | WARN | `weak-wording` | Use precise words, for example "many" for "a lot of". | | WARN | `gendered-language` | Use gender-neutral words. | | WARN | `sentence-length` | Keep a sentence to 25 words, or 20 words in an ordered list item. |

The linter counts words for each full sentence, also when the sentence wraps over many lines. It does not check the length of headline titles.

Run the batch command

Run this command from the project root. Give the files that you changed:

emacs -Q --batch -l ~/.kiro/skills/ste-lint/ste-lint.el -f ste-lint-batch FILE.org...

The command writes each finding to standard error in this format:

FILE:LINE:COLUMN: SEVERITY [CATEGORY] MATCH -- SUGGESTION

The last line gives the number of errors and warnings. The exit status is 1 when there is at least one ERROR finding, and 0 otherwise.

Correct each ERROR finding in your text. For a WARN finding, decide if the text breaks STE. A WARN finding can be a false positive, for example "set up" as a noun.

Use the Flymake backend

To see the findings while you edit an Org buffer, load the file and turn on the backend:

(load "~/.kiro/skills/ste-lint/ste-lint.el")
(add-hook 'org-mode-hook #'ste-lint-flymake-setup)

Run `M-x ste-lint-flymake-setup` to turn on the backend in one buffer only. When the backend is on, an agent can read the findings with the `get-diagnostics` MCP tool. The findings carry the prefix `STE`.

Change the rules

Edit the tables `ste-lint-pattern-rules` and `ste-lint-substitution-rules` in `ste-lint.el`. Add a test for each new rule to `ste-lint-tests.el`. Then run the tests:

./run-tests.sh

Each rule must trace to ASD-STE100. Do not add rules for other style guides. The rule tables are a port of `ste-lint.pl` in the EUSCDanubeWikiCDK package. If you change a rule, tell the user, so that the user can change the Perl script too.

Limits