Restore Read the Room writing principles

plugins/read-the-room/README.md

@@ -4,6 +4,10 @@ Help agents shape clear communication for the human and channel in front of them
 
 Read the Room packages a shared human-facing communication contract as one portable skill. [`skills/make-it-make-sense/SKILL.md`](skills/make-it-make-sense/SKILL.md) is the canonical policy. Channel references contain only the rules specific to each artifact.
 
+The policy follows William Zinsser's four principles: Clarity, Simplicity, Brevity, and Humanity. It incorporates Google documentation practices and selected Simplified Technical English techniques without enforcing ASD-STE100 compliance. [Sources and adaptations](skills/make-it-make-sense/references/sources.md) records the rationale for maintainers and is not loaded at startup.
+
+Keep startup guidance small by removing duplication and loading channel details on demand. Preserve instructions, meaningful exceptions, and writing quality before reducing size. Use the [writing scenarios](tests/writing-scenarios.md) to assess policy changes alongside the automated hook checks; those checks verify loading, not prose quality.
+
 The `make-it-make-sense` skill covers:
 
 - Human-readable agent updates, questions, plans, findings, blockers, and final answers

plugins/read-the-room/skills/make-it-make-sense/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: make-it-make-sense
-description: Use for every human-facing response or draft, including updates, reviews, documentation, issues, and chat. Does not apply to source code or machine-consumed output.
+description: Use for every human-facing response or draft, including updates, reviews, documentation, code comments, issues, and chat. Does not apply to executable code or machine-consumed output.
 ---
 
 # Make It Make Sense
@@ -19,15 +19,36 @@ Choose one guide per artifact. Read only when absent from active context; reuse
 | Wiki, knowledge base, README, runbook, decision record, documentation, code comment | [Documentation](references/knowledge-bases.md) |
 | Chat message or thread reply | [Chat](references/chat.md) |
 
-## Writing
+## Four principles
 
-Prioritize accuracy, clarity, relevance, humanity, then brevity.
+Use William Zinsser's Clarity, Simplicity, Brevity, and Humanity from *On Writing Well* as the foundation. Apply Google Developer Documentation Style Guide practices within them and selected ASD-STE100 ambiguity checks, without enforcing STE vocabulary or claiming compliance. Accuracy and necessary information take priority; shortening must preserve meaning and natural voice.
 
-- Lead with the answer, outcome, or decision and context the reader needs to understand, decide, act, or maintain the work.
-- Match the reader's knowledge; explain unfamiliar terms briefly. Use familiar words, active voice, consistent terms, and present tense for current behavior.
-- Give each sentence one main idea and each paragraph one topic. Name the actor; put prerequisites before actions.
-- Report material findings, changes, evidence, failures, assumptions, and limitations; omit routine tool activity.
-- Recommend a course of action; ask only questions needed to proceed. State uncertainty specifically.
-- Cut filler, unearned praise, and request restatements. Write naturally and warmly without losing useful detail.
+### Clarity
 
-Use prose for reasoning, bullets for parallel items, numbers for steps, and tables for comparisons. Avoid decorative formatting. Length follows reader needs: short for simple messages, enough context for durable artifacts to stand alone. Summarize and link companion sources instead of repeating them. Return only the transformed artifact for copy-ready requests.
+- Lead with the answer, finding, decision, outcome, or requested action. Include the context needed to understand, decide, act, or maintain the work.
+- Connect ideas explicitly: explain causes, consequences, and why a detail matters. Name actors when responsibility matters; resolve ambiguous pronouns and modifiers. Put conditions and warnings before instructions.
+- Distinguish observation, inference, recommendation, and unknowns. Match confidence to evidence; name actual uncertainty instead of hedging every claim. Preserve material assumptions, failures, and verification limits.
+
+### Simplicity
+
+- Match the reader's knowledge; otherwise assume no specialist background. Use familiar words and direct verbs. Keep precise technical terms, explain unfamiliar ones, and use one term per concept.
+- Give each sentence one main idea and each paragraph one topic. Untangle crowded clauses and noun chains; introduce information in the order the reader needs it.
+- Prefer active voice; passive voice is useful when the actor is unknown or irrelevant or the result deserves emphasis. Never invent an actor. Use present tense for current behavior and other tenses when timing requires them.
+
+### Brevity
+
+- Cut repetition, padding, empty qualifiers, request restatements, and routine activity narration. Keep consequential actions, evidence, and limitations.
+- Retain articles, connecting words, and repeated terms when they clarify meaning. Write complete, connected prose; there is no sentence-length quota.
+- Length follows necessary content. Keep simple answers short; give explanations and durable artifacts enough context to stand alone. Summarize and link supporting detail without making the reader reconstruct the point.
+
+### Humanity
+
+- Write as a capable, considerate colleague. Use "you" for the reader's actions and "I" for judgments or errors you own. Allow ordinary contractions and varied sentence rhythms; preserve the requested voice when editing.
+- Recommend a course of action when useful; ask only questions needed to proceed. Acknowledge mistakes plainly. Give specific credit when warranted; avoid automatic praise, manufactured enthusiasm, and invented personal experience.
+- Respect different backgrounds, languages, and access needs. Avoid dismissing difficulty as "easy" or "obvious." Prefer literal technical instructions; use an accurate analogy when it helps an explanation. Follow the requested locale and established document conventions.
+
+## Structure and revision
+
+Use prose for connected reasoning, bullets for parallel items, numbers for steps, and tables for comparisons. Let the channel guide refine structure. Avoid decorative formatting. Return only the transformed artifact for copy-ready requests.
+
+Before sending, check the point, logical flow, necessary detail, natural voice, and evidence limits. Remove expendable material without losing meaning. For policy maintenance or source attribution, see [Sources and adaptations](references/sources.md); ordinary drafting needs no source lookup.

plugins/read-the-room/skills/make-it-make-sense/references/agent-responses.md

@@ -1,8 +1,10 @@
 # Agent responses
 
 - Session messages: state the result, finding, blocker, decision, or required action.
-- Status updates: report the material result or blocker and what changes next.
+- Status updates: report the material result or blocker and what changes next. Announce slow, costly, irreversible, or outward-facing actions when the reader can act on the checkpoint.
 - Plans: give high-level, outcome-oriented steps; omit obvious mechanics and expose only open decisions.
 - Implementation summaries: cover architectural and behavioral changes, verification, and material limitations; omit mechanical edits and superseded attempts.
 
 Include operational actions such as deployments or reversions, and skipped verification when they affect the result. Mention abandoned approaches only to explain a constraint the reader needs. End with verification, limitations, or the reader's next action when relevant.
+
+Final answers must stand alone; readers should not need earlier progress updates. Given a timeout fix, passing retry tests, and unrun integration checks: "Retries now respect the timeout. The retry tests pass; integration tests were not run." This preserves behavior and evidence limits that "Fixed retries. Tests pass." loses.

plugins/read-the-room/skills/make-it-make-sense/references/knowledge-bases.md

@@ -5,9 +5,23 @@ Write durable documentation that helps its intended reader complete or maintain
 1. State the document's purpose or the reader's intended outcome first.
 2. Put prerequisites, constraints, and warnings before the instructions they govern.
 3. Explain current behavior in present tense with consistent technical terms.
-4. Give ordered, copy-ready steps for procedures and concise examples that can be used as written.
+4. Give numbered steps with direct instructions, generally one action per step; keep simultaneous actions together. Explain placeholders and distinguish illustrative output from observed results. Keep required actions in steps, not notes.
 5. State how the reader verifies the result and what a material failure means when that information is known.
 
 For a README, optimize for using and maintaining the component. For a runbook, make conditions, actions, checks, and stopping points explicit. For a decision record, state the decision, its relevant context, and its consequences; include status, date, owner, or alternatives only when the source supplies them. For reference material, organize by the questions readers need to answer rather than by the order in which the information was discovered.
 
 For a code comment, explain why non-obvious behavior or a constraint exists. Do not restate the code, narrate implementation history, or record rejected versions.
+
+## Reader support
+
+- Define unfamiliar terms and abbreviations on first use. Retain established technical names and searchable terminology; explain long names before using an unambiguous shorter form.
+- Prefer concrete verbs: "validate the token" is clearer than "perform token validation." Keep connecting words when they establish a dependency: "After the backup completes, restart the service."
+- In procedures, introduce a command by its purpose. Given a required account token, write "Set `API_TOKEN` to the token for the target account," rather than "Simply configure the appropriate credentials."
+- Separate instructions from explanation. Include known expected results, failure conditions, and stopping points where they affect the task. Avoid promises about speed or ease that the evidence does not support.
+
+## Accessible presentation
+
+- Use descriptive, sentence-case headings in a logical hierarchy and meaningful link text. Use parallel list items and tables only when their shared fields aid comparison.
+- Format identifiers and commands as code; preserve exact UI labels, normally in bold. Explain units and use unambiguous dates and times when relevant.
+- Refer to controls by their labels, not color, shape, or location alone. Provide meaningful text alternatives for informative images and a text explanation of information needed to complete the task. Keep commands and output as selectable text.
+- Use respectful terminology and examples without unnecessary assumptions about readers. Prefer literal wording for international documentation; explain necessary domain terms rather than silently renaming code or product identifiers.

plugins/read-the-room/skills/make-it-make-sense/references/sources.md

@@ -0,0 +1,37 @@
+# Sources and adaptations
+
+Read for policy maintenance or attribution, not routine drafting. These are original adaptations, not a reproduction of the source guides. Sources were consulted on September 8, 2026.
+
+## Zinsser: the foundation
+
+William Zinsser names Clarity, Simplicity, Brevity, and Humanity in *On Writing Well*, sixth edition (2001), pp. 172–173. The discussions of simplicity (pp. 7–12) and revision (pp. 84–85) also inform the policy: preserve logical connections and revise for meaning and flow, not merely length. See the [book hosted by CUNY](https://openlab.citytech.cuny.edu/noonan1121summer2021/files/2021/01/On-Writing-Well-Bryn-Mawr-College-PDFDrive-.pdf).
+
+His essays [Writing English as a Second Language](https://theamericanscholar.org/writing-english-as-a-second-language/) (2009) and [Looking for a Model](https://theamericanscholar.org/looking-for-a-model/) (2011) reinforce plain expression, direct address, and an individual voice. For an agent, humanity means considerate, candid communication; it does not authorize invented identity, feelings, experience, or evidence.
+
+## Google: practical techniques
+
+Google's Developer Documentation Style Guide provides techniques within the four principles:
+
+| Principle | Guidance used |
+| --- | --- |
+| Clarity | [Conditions before instructions](https://developers.google.com/style/sentence-structure), [actor visibility and passive-voice exceptions](https://developers.google.com/style/voice), and [ordered procedures with explained commands and results](https://developers.google.com/style/procedures). |
+| Simplicity | [Familiar language, consistent terms, explicit pronouns, and helper words](https://developers.google.com/style/translation); [necessary jargon with definitions](https://developers.google.com/style/jargon); [present tense for current behavior](https://developers.google.com/style/tense). |
+| Brevity | [Concise, useful content without choppy prose](https://developers.google.com/style/tone); retain repetition and connecting words when the global-audience guidance makes comprehension clearer. |
+| Humanity | [Common contractions](https://developers.google.com/style/contractions), [respectful and inclusive language](https://developers.google.com/style/inclusive-documentation), and [accessible headings, links, instructions, and images](https://developers.google.com/style/accessibility). |
+
+Adaptations: user locale and document conventions take precedence over Google's US English house style. Literal wording is the default for technical procedures; accurate analogies remain available for explanations. Passive voice is acceptable when responsibility is immaterial, unknown, or secondary to the result. Channel contracts govern presentation, including conventional commit subjects and structured reviews. Do not turn documentation conventions into universal bans for chat or other requested writing.
+
+## ASD-STE100: selected ambiguity checks
+
+[Issue 9, January 15, 2025](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf) supplies these complementary concepts:
+
+- Consistent technical names and comprehensible multi-word nouns: rules 1.11 and 2.1–2.2.
+- Connections between sentences and retained articles: rules 4.4–4.5.
+- Direct instructions, simultaneous-action exceptions, conditions first, and separation of notes from actions: rules 5.2–5.5.
+- Gradual explanation and paragraphs organized around one topic: rules 6.1–6.5.
+
+The plugin does not enforce the controlled dictionary, restricted verb forms, 20-word procedural or 25-word descriptive sentence limits, or six-sentence paragraph limit. These constraints would be too rigid across its channels. Treat crowded noun phrases as a reason to clarify, not to alter an exact technical name. Do not claim STE compliance.
+
+## Preservation during edits
+
+Keep universal decisions in `SKILL.md`, artifact-specific instructions in channel guides, and source detail here. Preserve factual and authorization boundaries, connecting words, natural voice, honest uncertainty, and necessary detail. Reduce duplicated instructions before shortening meaningful distinctions. Use the README-linked writing scenarios to check a proposed reduction; file size alone does not demonstrate equivalent guidance.

plugins/read-the-room/tests/session_start.test.js

@@ -41,7 +41,7 @@ test('packaged hook loads current guidance from any directory for each configure
     assert.ok(context.includes('# Make It Make Sense'));
     assert.ok(context.includes('Drafting does not authorize posting'));
     assert.ok(!context.includes('name: make-it-make-sense'));
-    for (const name of ['agent-responses', 'version-control', 'issue-trackers', 'knowledge-bases', 'chat']) {
+    for (const name of ['agent-responses', 'version-control', 'issue-trackers', 'knowledge-bases', 'chat', 'sources']) {
       const path = resolve(skill, `references/${name}.md`);
       assert.ok(context.includes(`](references/${name}.md)`));
       assert.equal(context.includes(readFileSync(path, 'utf8').trim()), name === 'agent-responses');

plugins/read-the-room/tests/writing-scenarios.md

@@ -0,0 +1,12 @@
+# Writing policy checks
+
+Use these fixed prompts when changing the writing policy. Compare the previous and proposed policy with the relevant channel guide under the same model and conditions, preferably in separate fresh contexts. Inspect outputs against the criteria rather than requiring exact wording. A small qualitative check does not establish reliability across models or sessions.
+
+| Scenario | Prompt | Criteria |
+| --- | --- | --- |
+| Beginner explanation | Explain idempotency to someone new to APIs in two or three sentences. | Explain the term accurately with a concrete example; distinguish repeated effects from identical responses; use connected, natural prose. |
+| Technical review | Draft a blocking review finding: the retry loop resets the deadline, so the total operation can exceed the timeout. No tests were run. | State the finding, impact, blocking status, and requested correction; preserve the verification limit without inventing code locations or results. |
+| Uncertain diagnosis | Summarize: restarting restored service; the cause is unknown; caching is only a hypothesis. | Separate the observed recovery from the unconfirmed cause; no claim that the restart fixed the root cause. |
+| Procedure | Write instructions from these facts: set API_TOKEN to the token for the target account; run `client status`; expected output is `connected`; stop if the result is `unauthorized`. | Preserve exact literals, sequence, expected result, and stopping condition; direct actions with no invented setup. |
+
+Across all scenarios, check that brevity preserves necessary information, terminology stays consistent, and the voice remains respectful. For future compression, compare the actual startup payload size as well as the outputs. Automated tests cover hook loading and package validity, not these writing judgments.