pi-simple-english 0.6.0 → 0.7.0

package/README.md

@@ -1,12 +1,12 @@
-# pi-simple-english
+# simple-english for `pi`
 
-Lint prose and code comments with `simple_english`, from inside pi.
+A `pi` package that lints the prose the agent writes.
 
-The package adds two things to pi:
-
-- the `se_lint` tool, which lints a file or a directory
-- the `simple-english-lint` skill, which tells the agent to lint the
-  prose it writes and fix every finding
+The package ships the `lint-simple-english` skill, the
+`write-simple-english` skill, and the `se_lint` tool. The tool lints
+a file or a directory. The write skill carries the rules, so the
+agent writes clean prose the first time. The lint skill tells the
+agent to lint the prose it writes and fix every finding.
 
 ## Prerequisites
 
@@ -20,6 +20,10 @@ gem install simple_english
 
 For yourself, on every project:
 
+```bash
+pi install npm:pi-simple-english
+```
+
 For one project, with the team, install into the project instead. Run
 the install with `-l` from the project root:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simple-english",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Lint prose and code comments with the simple_english plain-English rules.",
   "type": "module",
   "license": "MIT",

package/skills/{simple-english-lint → lint-simple-english}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: simple-english-lint
+name: lint-simple-english
 description: Lint prose with simple_english after writing or editing documentation,
   READMEs, or code comments. Use when the agent writes prose, when asked to lint
   or simplify text, or when a doc change lands.

package/skills/write-simple-english/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: write-simple-english
+description: Write plain English on the first pass. Use whenever the
+  output is prose, such as READMEs, docs, comments, replies, or any
+  other text a reader must understand. Use when asked for simple
+  English or no jargon.
+metadata:
+  inspired-by: ASD-STE100 Simplified Technical English
+---
+
+Write prose (READMEs, docs, comments) for a reader whose task is to
+understand the idea behind the words. They value clarity and
+conciseness. Their attention is limited, and every word competes for
+it. Minimize their cognitive load: common words, short sentences,
+one idea at a time.
+
+These rules are a controlled language like ASD-STE100, the aerospace
+standard for maintenance manuals. They bind: a sentence
+outside them is an error, not a style choice.
+
+## How to write
+
+### Mechanics
+
+Write the words in full. No contractions, no semicolons, no
+em-dashes. Two short sentences beat one joined pair. Write "A or B,
+or both", not and/or. Write "for example", not e.g., and "that is",
+not i.e. Name the items instead of etc.
+
+### Verbs
+
+Use the active voice. Say who does the action. Use simple tenses.
+State a requirement with can, will, or must. Put the condition
+before the command: "If the port is taken, pick another." No -ing
+phrase after a comma. Start a new sentence.
+
+### Keep it short
+
+Cut every word that carries no idea. One idea per sentence. One idea
+per paragraph. A sentence carries at most 20 words in instructions,
+25 in explanations. A paragraph carries at most 6 sentences.
+
+### Protect the code
+
+When you rewrite, leave code, identifiers, commands, flags, file
+paths, quoted errors, and product names untouched. The rules govern
+the prose around them.
+
+## Swap slop for short words
+
+The lists name the common offenders. When a word does what a heading
+bans, swap it, listed or not.
+
+### Filler
+
+- Empty modifiers: just, very, really, extremely, vibrant, nuanced,
+  multifaceted
+- Throat-clearing openers: it is worth noting, it is important to, is
+  designed to, aims to, in conclusion, in summary, at the end of the
+  day
+- Sign-offs and invitations: "I hope this helps", "let's dive in"
+
+### Wordiness
+
+- to, not in order to
+- because, not due to the fact that
+- if, not in the event that
+- for, not when it comes to
+- before, not prior to
+- by default, not out of the box
+- state the condition, not "as needed"
+
+### Corporate voice
+
+- use, not leverage
+- help, not facilitate
+- help, not foster
+- use, not harness
+- make simpler, not streamline
+- function, not functionality
+- you can, not enables you to
+- corrects, not addresses the issue
+- show, not showcase
+- has, not boasts
+- make sure that, not ensure
+- improve, not enhance
+- increase, not elevate
+
+### Hype
+
+- new, not groundbreaking
+- change, not revolutionize
+- say what changes, not transformative
+- complex, not intricate
+- important, not pivotal
+- careful, not meticulous
+- full, not holistic
+- model, not paradigm
+- area, not realm or landscape
+- interaction, not interplay
+- read, not delve into
+- many, not plethora
+- delete tapestry, testament, and synergy
+- internally, not under the hood
+
+### Connectors
+
+- also, not furthermore
+- but, not notwithstanding or that being said
+- start, not embark
+- busy, not bustling
+- give the location, not "nestled"
+- say what it does, not "gracefully handles"
+
+## Then lint
+
+After the text exists, run the lint-simple-english skill on it. The
+draft is done when the lint result is clean.
+
+## In chat
+
+The reply is prose too, and every rule above applies to it. Answer
+in the first sentence, then support it. Headers and bold belong in
+documents. A list only for steps in order, a code block only for
+text the reader must copy. Define a term in a few words at first
+use. The linter checks files, so the reply carries the rules on its
+own.