plain-language-writing

plain-language-writing

Two independent rule sets. A caller states which one applies — COMMS for text read once, live, in the moment; ARTIFACT for prose in a persistent file that gets re-read and reviewed. Don't cross-apply them; they're tuned for different reading conditions.

These rules operationalize standards with credible backing (ISO 24495-1, Kimble's plain-language work, EARS, INCOSE's Guide for Writing Requirements) but aren't each individually proven — treat them as the best currently-evidenced approach, not a guaranteed fix. See the research doc above for what's well-supported (the pronoun rule, COMMS #4 / ARTIFACT #3) versus reasonable-but-unproven. COMMS #5 (structure) has no empirical backing at all — an earlier version of it (A5) was dropped from the research for lack of evidence; it's kept here only as a stylistic default, not a proven rule.

COMMS — live agent-to-user text

Interview questions, confirmation/recap prompts, status updates, walkthrough questions, blocker/pause/stop messages.

1. Sentence length. Roughly 20 words or fewer. Split anything longer.

2. One clause per sentence. No "and/but/which" joining two distinct ideas.

3. No idioms, metaphors, or humor. Say it literally (not "let's dive in," "heads up," "ballpark").

4. No ambiguous pronoun. When a sentence introduces two things of similar weight, don't refer back with "it/this/that" — name the one you mean. Doesn't require eliminating every pronoun, only where more than one referent is plausible.

5. Causal/multi-step explanations use labeled structure, not a dense paragraph. When explaining a root cause or a multi-step process (why something failed, what happens as a result), break it into short ALL-CAPS section labels plus numbered steps or IF/THEN for branching logic. Doesn't apply to short interview questions or one-line status updates — those stay as plain sentences; forcing structure onto them reads as stilted.

   Shape to follow:

   PROBLEM.
   <one or more sentences naming what's wrong>
   
   WHY THIS HAPPENS.
   <mechanism, as numbered steps if there's a sequence>
   1. ...
   2. ...
   
   THE ROOT CAUSE.
   IF <condition> THEN <result>.
   IF <other condition> THEN <other result>.
   
   CONCLUSION.
   <one sentence confirming or correcting the user's read>
   
   NEXT STEP.
   <what happens next, or what's still open>
   

ARTIFACT — persistent artifact prose

Free-running prose in proposal.md, specs/*.md, design.md, tasks.md, align.md. Never overrides the structural formats those artifacts already mandate (### Requirement / #### Scenario blocks, WHEN/THEN, checkbox syntax, delta-operation headers, SHALL/MUST usage).

1. No vague or escape-clause words. Avoid "adequate," "reasonable," "as appropriate," "where possible," "etc." State a measurable criterion or an explicit list instead.
2. One obligation or decision per sentence. Don't join two requirements or decisions with "and/or."
3. No ambiguous pronoun. Same condition as COMMS #4.
4. Normative keywords stay in requirement blocks. SHALL/MUST/SHOULD in ALL CAPS only inside an actual ### Requirement statement — never capitalized in narrative prose (proposal.md, design.md rationale).
5. One term per concept. Reuse the same name across proposal.md, specs/*.md, design.md, and tasks.md — don't drift between synonyms (e.g. "user" / "actor" / "consumer").