| name | readable-message |
| description | Reduce reader cognitive load in plain-text messages — Slack, chat DMs, SNS, plain-text email — where no markdown rendering is available. Phone-first ordering and chunking (self-contained first line, one topic, 1-3-line chunks), an ASCII tag vocabulary, and optional script-specific decoration with strict usage rules. Use when writing or rewriting a chat message, announcement, request, or notification, or when asked to "make this message readable/scannable", "format this for Slack/DM", or shown a wall-of-text message. Not for surfaces that render markdown, and not for argumentative prose. |
Readable plain-text messages
Foundation
The constraints come from the reading environment, not the language:
- A phone viewport shows roughly 12-15 lines; longer messages collapse behind "Show more".
- Notification previews and channel lists show only the first line.
- Chat apps use proportional fonts and re-wrap text. Column alignment and
leading-space indentation do not survive.
- Readers scan before they read: first "is this for me?", then the one fact they need.
Admission rule for symbols: a symbol earns its place only by showing structure —
a boundary, a hierarchy, a key-value pair, a state, or a sequence. Symbols that
perform attention or emotion (eye-catchers such as ＼ ／, decorative or tone emoji)
belong to register and taste, not cognitive load; this skill never adds them, and
uses no emoji at all.
The skill has three layers. Blind A/B testing of drafts showed that Layer 1 — the
invisible ordering discipline — carries nearly all of the benefit; the visible
decoration is a minor, situational gain. Apply the layers in order and stop as
early as you can.
Layer 1 — Ordering and chunking (mandatory)
- First line = the point, self-contained. A complete plain statement with its
own subject, no symbols. "Yes, we can" fails as a notification preview;
"We can ship search on Friday" works. If one caveat decides whether the reader
needs to keep reading ("US only — no impact on us"), put it in the first two lines.
- One message, one topic. Background, timelines, and side questions go to a
thread reply or a linked doc.
- Chunks of 1-3 lines, separated by blank lines. A
Key: value block or a
list counts as one chunk, however many lines it has — the rule governs prose.
- Break lines only at semantic boundaries — after a sentence, or after a major
clause. Never hard-break mid-sentence to control line width: the client re-wraps
and produces ragged fragments. (The Semantic Line Breaks spec, sembr.org, reaches
the same rule for markup sources.)
- Cap at ~15 lines. Longer means restructure, move detail to a thread, or link out.
- Number anything the reader must choose from or refer back to. Numbers make
items pointable — a reply becomes "option 2" (selection) instead of a restatement
(recall).
- Each quotable line carries its own subject. Thread replies strip surrounding
context. "$5,000/year" alone is ambiguous; "store operators pay Google $5,000/year"
survives being quoted. Applies to channels and threads; in a 1:1 DM, where lines
are read in sequence, this rule may yield to tone.
- Prefer absolute dates over relative ones. Messages are read later than they
are sent and resurface in search: "next Wednesday" rots, "Wed 11/26" does not.
If the calendar date is not known, keep the relative wording rather than guess.
Evidence grades, so the skill stays honest about what it knows:
| Rule | Grade |
|---|
| Chunking (3) | research-backed (working-memory / chunking literature) |
| First line (1), no mid-sentence breaks (4), length cap (5) | UI constraint — follows mechanically from previews, re-wrapping, collapse |
| The rest (2, 6, 7, 8) | convention — well-attested in git commit format, RFC style, and plaintext email culture |
Layer 2 — ASCII tag vocabulary
When Layer 1 alone is not enough, borrow from code comments, commit messages, and
RFCs. This vocabulary is ASCII, greppable, survives copy-paste into any tool, and
is tolerable to screen readers.
- Line-head type tags —
NOTE:, WARNING:, TL;DR:, ACTION: — declare what
kind of line follows. At most one or two per message.
Key: value lines for lookup facts (When: Fri 10:00, Where: Studio A).
Use when there are 3+ parallel facts; fewer reads better as prose.1. 2. for sequences and choices; - for unordered lists.-> means consequence, and nothing else. One symbol, one meaning per message:
write "i.e." and "then" as words instead of overloading the arrow.[x] / [ ] for done/undone status.- Never use a live tag token as an example in the same message — quote it
(a "NOTE:"-style tag), or the reader parses a false tag.
Layer 3 — Script-specific decoration (optional — earn it)
Section headers, dividers, and bracket labels help desktop scanning and cost
phone screens and screen readers. Rules of admission:
- No headers or dividers in a message under ~10 content lines (blank lines
don't count). A blank line already separates.
- A header must cover everything under it: one section, one topic. A header that
labels only part of its section breaks scanning for the rest.
- Dividers are redundant next to a header plus a blank line. If you use one,
keep it short (
---); a 20-char rule line can itself wrap into an orphan stub,
and a screen reader announces every character of it.
- Bracketed key labels (Japanese 【】) only with 3+ parallel keys.
- Never column-align across lines and never indent continuations with spaces —
both die in proportional fonts.
Per-script vocabularies (Latin/ASCII, Japanese/CJK, caseless scripts) and their
pitfalls: see references/scripts.md.
Send-time checklist
- Would the first line alone, in a notification, tell the reader the point and
whether it concerns them?
- One topic? Chunks of 1-3 lines? 15 lines or fewer?
- Any hard break inside a sentence? Remove it.
- Does each symbol have exactly one meaning in this message?
- Would each line survive being quoted alone in a thread?
- Is every header honest about its whole section? Is decoration earned (~10+ lines)?
- Register — greetings, emoji, formality — is the room's call, not this skill's.
Match the channel's existing tone. (Culture-dependent; no universal rule exists.)
Before / After
Before:
Hi! Quick question — we talked about the release last week, and QA flagged a
performance issue in the search revamp that isn't fixed yet, so we need to decide
whether to include it. If we don't, we can still ship Tuesday, but if we do it'll
take about three more days, so we'd ship Friday instead. What do you think works
best? Thanks!
After:
Decision needed by tomorrow: include the search revamp in this release?
QA flagged a performance issue in the revamp; the fix needs ~3 days.
- Ship without it -> release stays Tuesday
- Include it -> release moves to Friday
Reply with a number and I'll proceed.
Every Layer 1 rule is visible here; the only Layer 2 items are the numbers and one
arrow. Nothing from Layer 3 was needed — that is the common case.
Scope and limits
- For transmission: requests, announcements, status updates, explanations.
Not for argumentative or persuasive prose — this structure dismantles an
argument's flow into disconnected assertions. Asked to persuade anyway? Reframe
it as a transmission: a proposal plus a concrete ask, the few load-bearing facts
numbered, and the full case left to a doc, thread, or meeting.
- Not for markdown-rendering surfaces (READMEs, docs, GitHub issues): use real
markdown there.
- The failure mode of this style is imitation without discipline: decoration wrapped
around unordered text signals structure that is not there, which is worse than
honest prose. When in doubt, apply Layer 1 and stop.
- Reformatting forces compression — expect the result to be much shorter than the
source. If essential nuance is being squeezed out, the content may be an argument,
not a transmission; see the first bullet.
Lineage
These conventions are described, not invented, following long-lived plain-text cultures:
git commit format (summary line, blank line, body); TODO/FIXME code-comment tags;
RFC 2119 capitalized keywords and man-page section headers; setext (1992) →
Markdown, whose stated "single biggest source of inspiration" was plain-text email;
Semantic Line Breaks (sembr.org). Steve Krug's Don't Make Me Think makes the
same demand of interfaces that this skill makes of messages: the reader should
get it by looking, not by working.
