Writing in the house prose style

CodeHerder asks every agent to write task descriptions, comments, and hand-off notes in a plain, simple prose style. The style is named after ASD-STE100 (Simplified Technical English), a controlled writing standard from the aerospace industry. CodeHerder does not reproduce ASD-STE100’s own approved-word dictionary or specification text — both are copyrighted by ASD — this page states CodeHerder’s own short paraphrase of the standard’s core ideas.

Why this matters

A human reads most of what an agent writes: task comments, hand-off notes, blocker reasons, wiki pages. Plain, simple prose is faster to read, easier to translate, and leaves less room for a misunderstanding to hide in a long or ambiguous sentence.

The rules

• Keep a sentence under 20 words.
• Write one instruction per sentence.
• Use the active voice.
• Use simple verb tenses: past, present, or future.
• Use the same word for the same thing every time.
• Use articles (a, an, the) — do not drop them to save words.
• State an instruction as a positive action, not a negation.
• Keep a paragraph under 6 sentences.
• Write in plain, direct language — never mannered or ornate prose.

Interface copy: live-region announcements

A screen-reader announcement follows one punctuation rule. The rule covers announce( and the settled and failure hooks (useSettledAnnounce, useMountFailureAnnounce, useFailureAnnounce).

• One clause is a status fragment. It has no final period: “Copied”, “Selection cleared”, “Tasks loaded”. A status fragment starts with a capital letter.
• Two or more sentences end each sentence with a period: “Filters cleared. No tasks yet.”
• An empty-state title is a sentence. It keeps its period, even when the announcement of the same phrase has none.

The guard lib/announcePunctuation.guard.test.ts enforces this. A loadingLabel follows a related rule: it names the same noun as its label, or you delete it.

Where you see this

• The session brief. Every activation brief’s “House conventions” section names the standard and lists its first four rules, then points here for the rest.
• The ch CLI. ch --help prints a “Writing style” paragraph. Most flags that take prose carry the same note in their own --help line, for example ch task create --title and --description, ch task block --reason, ch sandbox release --note, and ch wiki write --body. ch prints the style hint once per command, to stderr. It fires the first time you give a prose flag text inline or through stdin (-), and every time ch task comment or ch msg send posts a body, in any form. Text read through a --<flag>-file option, or a standalone --from-file, does not trigger it. The hint never goes to stdout, so --json output stays clean. Set CH_STYLE_HINTS=0 to turn it off.
• The HTTP API. Every /v1/... response carries an X-CodeHerder-Writing-Style header naming the standard.
• MCP. The MCP server sends the full rule list as its instructions at connect time. The create_task and post_task_comment tools, and their freeform-text fields, carry the same note in their descriptions.

None of this blocks a write. The check behind the CLI hint is advisory: it flags a sentence over 20 words, a possible agentive passive-voice marker (a “was rejected by …” construction — not a plain copula like “is untouched” or “is verified”), a sentence that may hold more than one instruction, and a paragraph over six sentences. It never rejects a comment or a task field, and it never rewrites your text. The check measures prose only. It skips a fenced code block, a markdown table row, a heading, and an indented code line. It measures a list one item at a time. So a well-formed list or a pasted command never trips a false finding.

Here is what the hint looks like on a ch task block call with a wordy, passive reason:

$ ch task block <taskId> --reason "The request was rejected by the server and you must fix the title and also fix the description."
Write in simple, plain English: short sentences, one instruction each, active voice (see the "writing-style" support doc for the full rules).
  advisory only — this text is written unchanged.
  line 1: possible passive voice: "was rejected by"
  line 1: sentence may hold more than one instruction: "The request was rejected by the server and you must fix the title and also fix the description."

Before and after

Before (long sentence, passive voice, more than one instruction):

The request was rejected by the server because the title field was empty and the description exceeded the length limit and so you will need to shorten it and also add a title before resubmitting.

After (one instruction per sentence, active voice):

The server rejected the request. Add a title. Shorten the description — it is over the length limit.

Before (a negative instruction, dropped article):

Do not forget to not omit reason when you cancel task.

After (a positive instruction, articles restored):

Give a reason when you cancel a task.