# Writing Style Standard — MOS-STE (MANDATORY)

This guide defines how agents write. It sets one style standard per output type.
It is written in the standard it defines, as a worked example.

**Adapted, not compliant.** MOS-STE (Mosaic Simplified Technical English) is an
adapted profile of ASD-STE100. Mosaic does not license or certify against
ASD-STE100. Mosaic uses the load-bearing rules and fits them to agent work. This
is the same stance Mosaic takes toward DO-178B/C: use the rigor, do not claim the
certification.

## Scope — which standard governs which output

| Output type                                                                                                   | Standard                                                                    |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Technical documentation (READMEs, runbooks, PRDs, procedures, ADRs, guides, acceptance criteria, design docs) | **MOS-STE** (this guide)                                                    |
| Source code and code comments                                                                                 | **Google Style Guide** for the language (§4)                                |
| Inter-agent comms                                                                                             | MOS-STE by default (concise, structured)                                    |
| User-facing comms                                                                                             | **Per-user style choice** — read `USER.md` "Communication Preferences" (§5) |
| End-user prose the user owns (marketing, letters, personal writing, voice-matched content)                    | The user's declared voice. MOS-STE does NOT apply.                          |

**The user-voice carve-out is absolute.** Do not apply MOS-STE to content that
must carry a specific human voice (for example a cover letter, a personal
message, or marketing copy). That content needs the user's voice. MOS-STE would
damage it. When a project declares a voice profile, that profile wins.

## 1. Why one standard

Agent documentation drifts across projects. Different agents use different terms,
sentence styles, and structures for the same concept. Readers lose time.
Assumptions hide in ambiguous prose. One standard gives agents a clear target. It
gives reviewers a clear test.

## 2. Where MOS-STE matters most — verification artifacts

Apply MOS-STE hardest to acceptance criteria, witness predicates, gate
definitions, and alarm conditions. In prose, an ambiguous term produces a
confused reader. In a verification artifact, an ambiguous term produces a false
green — a check that passes without testing the claim.

The one-term-one-concept rule (rule 9) is the guard. When one word names two
concepts in one predicate, the check can test the wrong concept and still pass.

**Worked failure.** A rename used a witness predicate with three clauses: ref A
present, ref B absent, tip committed from this host. Every clause tested the git
_ref_ (the channel). The claim under test was about a _field inside the payload_.
The word "beacon" named two concepts in one sentence. Deleting ref B was the next
scheduled step. That step flips the last clause green and certifies a state in
which the payload still names the wrong host. The predicate was one planned action
away from a false green on its normal path. The payload field was never tested.

Rule: when N failure modes share one observable, the observable is not a
diagnostic. In a verification artifact, that ambiguity does not confuse a reader —
it certifies the defect.

## 3. MOS-STE rules

### 3.1 Sentence rules

1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or
   fewer for a description. (Reasoning and doctrine prose relaxes this limit —
   see §3.4. A future lint enforces §3.1, not §3.4.)
2. Write one instruction per sentence. In a procedure, give one command per step.
3. Use the active voice. Write "Run the script." Do not write "The script should
   be run."
4. Use the imperative for instructions. Start the sentence with the verb.
5. Use simple verb tenses. Prefer the present tense. Avoid the perfect and
   progressive tenses when a simple tense works.
6. Do not use an `-ing` form when it makes the meaning unclear.
7. Write positive statements. State what to do, not only what to avoid.

### 3.2 Word rules

8. Use one word for one meaning. Do not use the same word in two senses.
9. Use one term for one concept. Do not use synonyms for variety. Example: choose
   `secret`, `credential`, or `key` for each concept, and keep it.
10. Use articles (`a`, `the`). Do not drop words to save space.
11. Keep an approved-terms glossary per project. Add each domain noun and each
    chosen verb. Technical names (for example `Vault`, `cgroup`, `systemd`) are
    always allowed.
12. Define an abbreviation at its first use. Then use it consistently.

### 3.3 Structure rules

13. Use a list for parallel items or sequential steps. Do not put them in one long
    sentence.
14. Use a table for data with more than two dimensions.
15. Use parallel structure in headings and steps.
16. Repeat the noun. Do not use a pronoun when the reference is unclear.

### 3.4 Adaptation notes (where MOS-STE deviates from ASD-STE100, and why)

- **No licensed dictionary.** ASD-STE100 ships a controlled dictionary under
  copyright. MOS-STE uses per-project glossaries instead (rule 11).
- **Domain terms are allowed.** MOS-STE keeps every term the work needs.
- **Reasoning prose gets structure, not amputation.** Apply the sentence and word
  rules to design and doctrine writing. Allow the length a subtle argument needs.
  Readable-first beats rule-strict when the two conflict.

## 4. Code — Google Style Guide

Write source code to the Google Style Guide for the language (Python, TypeScript,
Shell, Go, and so on). Match the existing file when a local convention already
exists. Keep code comments to the MOS-STE sentence and word rules.

## 5. User-facing comms — a per-user choice

Mosaic is multi-user. Different users want different comms styles. The framework
already carries the selectable setting: `communicationStyle` (`direct` |
`friendly` | `formal`, default `direct`). `mosaic init` writes it, and the
builder renders it into the generated `USER.md` "Communication Preferences"
section. This guide adds the OUTPUT meaning of each value; do not invent new
values.

The builder renders the style as prose bullets, not the token name, so match on
the leading bullet the generated `USER.md` actually contains:

| `USER.md` leading bullet      | Style              | User-facing output                                                     |
| ----------------------------- | ------------------ | ---------------------------------------------------------------------- |
| "Direct and concise"          | `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. |
| "Warm and conversational"     | `friendly`         | Warmer register. Full sentences, explain reasoning, fewer tables.      |
| "Professional and structured" | `formal`           | Professional and structured. Thorough, with explicit recommendations.  |

This setting governs **user-facing comms only**. It does not change the
documentation standard (§3), which is always MOS-STE regardless of the value.

## 6. Enforcement

- **Now:** human review only. **No mechanical prose check exists today.** The
  pre-push gate runs typecheck, lint, build, and tests; it inspects no prose.
  Reviewers check output against the scope table and the MOS-STE rules by hand.
- **Future:** an MOS-STE lint check (built from the §3.1 sentence rules) and a
  Google-style linter in the pre-push gate. A future linter enforces §3.1, not
  §3.4 — see the note at rule 1.
