stack/packages/mosaic/framework/guides/WRITING-STYLE.md

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.