Conveying clearly
A statement, a question, an option set, a verdict, a resolution comment, a PR
description, a handoff, a map gist - one act: surfacing something to a reader
who did not watch this session. The shorthand you coined while reading code,
issues, and memory feels canonical to you and means nothing to them. That
asymmetry is invisible from the inside - a surface is always clear to its
author - so the fix is never to dumb the content down. Ground the vocabulary,
write plainly, lead with the point.
The register this governs
Every surface named above is one a colleague reads once and acts on. The
reader is deciding, not settling in, and the sentence craft below serves that.
Prose published under a person's name is a different register. An essay, a
post, a newsletter issue is read by a stranger under no obligation to keep
reading, and there the uniform short-sentence profile this contract prescribes
reads as machine-written. Published prose wants varied rhythm and a voice; this
contract does not govern it. Neither register outranks the other; the surface
being written picks one.
The reader test
Compose for a teammate who stepped away before this session started and reads
only what you are sending now. If acting on it - or trusting it - takes having
watched your exploration, the surface fails. Rewrite it before sending; do not
wait for "please clarify."
Lead with the point
One shape serves every surface:
- A line or two of shared context - what the reader needs, in their
vocabulary. Not a replay of your reasoning; they are deciding, not auditing.
- The point - the ask, the decision, the finding, the state - in one plain
sentence, ahead of any elaboration. A point buried under recited findings has
already failed the reader test.
- The why, as consequences - what taking it gets them, what it trades away.
- What follows - what it unblocks, invalidates, or commits to.
Ground every term
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Glossary: the file
docs/agents/domain.md names. Default: GLOSSARY.md
at the repository root, or, when a GLOSSARY-MAP.md exists there, the
per-context glossary it points at. A repository with no glossary simply has an
empty bucket 2.
Every load-bearing term belongs to one of three buckets:
- Everyday technical vocabulary - read without a glossary by any working
engineer (schema, migration, endpoint, rate limit).
- Ubiquitous language - defined in the project's glossary. Use these freely
and by preference, and never re-define them inline: define the private,
assume the shared.
- Glossed right here - at first use, in the surface the reader sees: "the
claim short-circuit (the check that skips permission resolution while an org
is unclaimed)".
Shorthand coined this session - by you, an inherited map gist, a ticket, a memory
file - is never automatically bucket 1, however settled it feels. Gloss it,
expand it, or drop it. A term that fits no bucket means you do not yet understand
the thing well enough to surface it; translate first.
No bare issue numbers as nouns. The citation rides in parentheses, never as a
subject or object: "the rule that agents can never provision organizations
(#69)" passes; "#93 tracks the resets" fails, because the number is doing a
noun's job.
Write plainly
Sentence craft, in the spirit of ASD-STE100 Simplified Technical English:
- One idea per sentence; roughly 20 words for an instruction, 25 for a
description.
- Active voice, simple present: "the migration drops the column". (The passive
is fine where the actor is genuinely unknown or irrelevant.)
- One term per meaning. A synonym reads as a second, different thing.
- No orphan "it" / "this" / "that" - name the thing again.
- No noun stacks: "agent permission grant scope resolver" is not a phrase.
Give reasons, not authority
"Board unanimous 4-0", "per the ratified ruling", "as decided" justify nothing to
a reader who was not there. Say what happens if the recommendation is taken, and
what is given up.
Reasons do not replace marking your lean. Where the surface has a mark, use
it: in a structured-question picker the recommended option goes first and its
label ends with (Recommended). A lean argued only in prose renders as no
recommendation at all. Holding no real lean, say so out loud - an unmarked list
reads as either "no recommendation" or "the marker got dropped". Never
manufacture a lean you do not hold.
When it lands badly
"I don't understand the question." "Wait, what?" "I'm not following where
you've got to." The answer is to re-pitch, not repeat - shortening the same
jargon is the classic wrong move, because vocabulary rather than length is
usually what broke. Name which terms were private, then rebuild: a little shared
context, the point in one plain sentence, grounded words. A human can invoke
this skill by name (/conveying-clearly, or "re-pitch that") to demand exactly
that of the last message.
Load when composing
- Option pickers - structured-question
headers, labels, descriptions, previews, the recommendation marker, and a
worked rewrite.
- Text that outlives the session -
resolution comments, map gists, handoffs, ticket bodies, decision records,
memory files: glossing, promote-or-drop, and the wayfinder map's Working
vocabulary.
Before you send
- Every noun understandable to a teammate who missed this session?
- Every load-bearing term plain, in the glossary, or glossed right here?
- The point in one plain sentence, behind at most a line or two of context?
- Short active sentences, one idea each, one term per meaning, no orphan "this"?
- Every why a consequence rather than an authority - and a real lean actually
marked, or its absence stated out loud?
- Any bare
#NNN doing a noun's job?
1---2name: conveying-clearly3description: >-4 The contract for a working surface a colleague reads once and acts on: a statement, a5 question or option set, a verdict, a ticket or PR comment, a status update. Use BEFORE6 composing one; `wayfinder` loads it automatically. Also trigger the moment someone says7 please clarify, I don't understand the question, wait what, or I'm not following where8 you've got to. Do NOT use for prose published under a byline (an essay, post or9 newsletter), or to compact a session for a successor (use `handoff`).10license: MIT11metadata:12 source: https://skillmd.com/skills/spencermarx/conveying-clearly13 credits: "The plain-language re-pitch is adapted from Matt Pocock's wait-what skill, https://github.com/mattpocock/skills (MIT)"14---1516<!-- Rationale: the plain-language spine borrows from the "wait-what" skill in17 github.com/mattpocock/skills (skills/productivity/wait-what): give a little18 context, write ASD-STE100 Simplified Technical English, speak the project's19 ubiquitous language. Upstream is a one-line re-pitch prompt a human fires20 after a message lands badly; here that becomes one move inside a standing21 contract ("When it lands badly"). Two of STE's rules are deliberately not22 carried over: its ~900-word approved dictionary (the three vocabulary23 buckets are the equivalent, and they admit the project's own domain24 language) and its blanket ban on the passive. -->2526# Conveying clearly2728A statement, a question, an option set, a verdict, a resolution comment, a PR29description, a handoff, a map gist - one act: **surfacing something to a reader30who did not watch this session.** The shorthand you coined while reading code,31issues, and memory feels canonical to you and means nothing to them. That32asymmetry is invisible from the inside - a surface is always clear to its33author - so the fix is never to dumb the content down. Ground the vocabulary,34write plainly, lead with the point.3536## The register this governs3738Every surface named above is one a colleague reads **once and acts on**. The39reader is deciding, not settling in, and the sentence craft below serves that.4041**Prose published under a person's name is a different register.** An essay, a42post, a newsletter issue is read by a stranger under no obligation to keep43reading, and there the uniform short-sentence profile this contract prescribes44reads as machine-written. Published prose wants varied rhythm and a voice; this45contract does not govern it. Neither register outranks the other; the surface46being written picks one.4748## The reader test4950Compose for a teammate who stepped away before this session started and reads51only what you are sending now. If acting on it - or trusting it - takes having52watched your exploration, the surface fails. Rewrite it before sending; do not53wait for "please clarify."5455## Lead with the point5657One shape serves every surface:58591. **A line or two of shared context** - what the reader needs, in their60 vocabulary. Not a replay of your reasoning; they are deciding, not auditing.612. **The point** - the ask, the decision, the finding, the state - in one plain62 sentence, ahead of any elaboration. A point buried under recited findings has63 already failed the reader test.643. **The why, as consequences** - what taking it gets them, what it trades away.654. **What follows** - what it unblocks, invalidates, or commits to.6667## Ground every term6869This repository's agent configuration should have been provided to you (the70`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the71defaults below and suggest the user run the `setup-aclarify-skills` skill.7273- **Glossary:** the file `docs/agents/domain.md` names. Default: `GLOSSARY.md`74 at the repository root, or, when a `GLOSSARY-MAP.md` exists there, the75 per-context glossary it points at. A repository with no glossary simply has an76 empty bucket 2.7778Every load-bearing term belongs to one of three buckets:79801. **Everyday technical vocabulary** - read without a glossary by any working81 engineer (schema, migration, endpoint, rate limit).822. **Ubiquitous language** - defined in the project's glossary. Use these freely83 and by preference, and never re-define them inline: **define the private,84 assume the shared.**853. **Glossed right here** - at first use, in the surface the reader sees: "the86 claim short-circuit (the check that skips permission resolution while an org87 is unclaimed)".8889Shorthand coined this session - by you, an inherited map gist, a ticket, a memory90file - is **never automatically bucket 1**, however settled it feels. Gloss it,91expand it, or drop it. A term that fits no bucket means you do not yet understand92the thing well enough to surface it; translate first.9394**No bare issue numbers as nouns.** The citation rides in parentheses, never as a95subject or object: "the rule that agents can never provision organizations96(#69)" passes; "#93 tracks the resets" fails, because the number is doing a97noun's job.9899## Write plainly100101Sentence craft, in the spirit of **ASD-STE100 Simplified Technical English**:102103- One idea per sentence; roughly 20 words for an instruction, 25 for a104 description.105- Active voice, simple present: "the migration drops the column". (The passive106 is fine where the actor is genuinely unknown or irrelevant.)107- One term per meaning. A synonym reads as a second, different thing.108- No orphan "it" / "this" / "that" - name the thing again.109- No noun stacks: "agent permission grant scope resolver" is not a phrase.110111## Give reasons, not authority112113"Board unanimous 4-0", "per the ratified ruling", "as decided" justify nothing to114a reader who was not there. Say what happens if the recommendation is taken, and115what is given up.116117Reasons do not replace **marking** your lean. Where the surface has a mark, use118it: in a structured-question picker the recommended option goes first and its119label ends with `(Recommended)`. A lean argued only in prose renders as no120recommendation at all. Holding no real lean, say so out loud - an unmarked list121reads as either "no recommendation" or "the marker got dropped". Never122manufacture a lean you do not hold.123124## When it lands badly125126"I don't understand the question." "Wait, what?" "I'm not following where127you've got to." The answer is to **re-pitch, not repeat** - shortening the same128jargon is the classic wrong move, because vocabulary rather than length is129usually what broke. Name which terms were private, then rebuild: a little shared130context, the point in one plain sentence, grounded words. A human can invoke131this skill by name (`/conveying-clearly`, or "re-pitch that") to demand exactly132that of the last message.133134## Load when composing135136- **[Option pickers](references/option-pickers.md)** - structured-question137 headers, labels, descriptions, previews, the recommendation marker, and a138 worked rewrite.139- **[Text that outlives the session](references/persisted-artifacts.md)** -140 resolution comments, map gists, handoffs, ticket bodies, decision records,141 memory files: glossing, promote-or-drop, and the wayfinder map's Working142 vocabulary.143144## Before you send145146- Every noun understandable to a teammate who missed this session?147- Every load-bearing term plain, in the glossary, or glossed right here?148- The point in one plain sentence, behind at most a line or two of context?149- Short active sentences, one idea each, one term per meaning, no orphan "this"?150- Every _why_ a consequence rather than an authority - and a real lean actually151 marked, or its absence stated out loud?152- Any bare `#NNN` doing a noun's job?