mosaicstack/stack
1
0
Fork 1
Code Issues 110 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960)

Browse Source 
F1: defaults/USER.md is never installed (generated from templates/USER.md.template
via buildCommunicationPrefs). Editing it was a no-op asserting a phantom setting —
exactly the false-green §2 warns against. Reverted.
F2: the framework already has communicationStyle (direct|friendly|formal). §5 now
maps THOSE values to output instead of inventing technical|prose|brief (rule 9).
Minor: §6 states no mechanical prose check exists today; rule 1 points at §3.4.

Written-by: jarvis (dragon-lin)
Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
jarvis
2026-07-30 15:24:17 -05:00
co-authored by Claude Fable 5
parent 6cc093afdb
commit caf40afc01
3 changed files with 25 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/mosaic/framework/guides/WRITING-STYLE.md
+24 -12
View File
@@ -58,7 +58,8 @@ it certifies the defect.
### 3.1 Sentence rules
1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or
fewer for a description.
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."
@@ -104,18 +105,29 @@ 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. Read the
`USER.md` "Communication Preferences" section and match the declared style.
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.
- **Default (no preference declared):** technical — MOS-STE structure,
readable-first.
- **Declared style wins.** If the user declares prose, warmth, or a specific
register, match it. The user's preference outranks the MOS-STE default for
user-facing comms. It does not change the documentation standard (§3).
Read the declared style in `USER.md` and match it:
| `communicationStyle` | User-facing output |
|---|---|
| `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. |
| `friendly` | Warmer register. Full sentences, explain reasoning, fewer tables. |
| `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 plus the pre-push gate. Reviewers check output against the
scope table and the MOS-STE rules.
- **Future:** an MOS-STE lint check and a Google-style linter in the pre-push
gate.
- **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.