Matrix Announcement

Content rules for Matrix announcements. matrix-communication does the sending.

The five rules

1. One headline, one purpose.
2. formatted_body in the HTML subset, not Markdown. body is the plaintext fallback — clients aren't required to parse Markdown.
3. Lists beat paragraphs. Enumerable items — findings, projects, failures, tickets — are a <ul>, however long each runs. A bold-led paragraph is emphasis, not structure.
4. Wrap code — and name the thing itself. Commands, paths, versions, IDs, env vars in <code>; multi-line in <pre><code class="language-…">. Name the identifier, not a category standing in for it (html-subset.md).
5. Layout > words → render an HTML card to PNG. Comparisons, dashboards and multi-row tables die in formatted_body.

Type tags (pick one — never stack)

New skill first release · Release feature version · Patch bugfix-only · Digest weekly roundup · Heads-up breaking change or deprecation · Postmortem incident · Findings investigation or audit · RFC proposal seeking feedback

Findings reports group by category of finding, never by who was wrong (structure.md).

Glyphs

One leading glyph at most. Never trailing decoration, multi-emoji ladders, 🚀, or 🎉. Approved: 🤖 bot · 📦 release · 🔧 tooling · 🛡 security · ⚠️ heads-up · 📋 digest · 🔬 RFC · 🚑 hotfix · 🔥 postmortem · 🔎 findings · ✨ new capability (sparingly).

Pre-send checklist

• One-line title at 1280px, opening with the change — not "we're excited to".
• URLs wrapped in <a>, destination as text.
• Every entity is a link: issue keys (even mid-sentence), versions → release page, MRs/PRs (project/path!N / org/repo#N), pipelines, commits. Status updates: one item per line, linked key first, blank lines between.
• Rules 3–5 applied: list structure, code wrapped, one glyph at most.
• Findings headings name the category, not the person.
• body reads standalone, not stripped HTML.
• m.notice for unattended automation, m.text otherwise; no @room unless it is an outage.
• Under 3000 chars, or threaded; image card if layout-heavy.

References

In references/:

• html-subset.md — allowed/banned tags, data-mx-*, naming the identifier
• structure.md — skeleton, length budget, m.text vs m.notice, how to send
• glyphs.md · anti-patterns.md — glyph table; wall-of-text, emoji ladder, mention storm
• image-cards.md — chromium → upload → m.image
• threading.md — threads, mentions, edits, redactions
• text-templates.md · templates/ · gallery.html — skeletons, HTML cards, preview