plainly · diff
git:20260922.6884e96 to git:20261013.4e5c041
13 added, 8 removed. Audit B to B.
---
description: >-
Explain something to a person in plain language, cause first. Invoked bare at
an answer that did not land — a re-asked question, a "just tell me",
punctuation doing the complaining — it re-explains that answer as a causal
chain; invoked with a question, it answers that question under the house rule,
investigation included; either way it shows the smallest concrete example of
what the answer says. Names six defects — symptom-as-finding, buried lede,
untranslated nouns, broken chain, fog, receipt — so one word calls out a bad
report.
---
This file is the procedure: the invocations, the pass, and the six defects it
runs a draft against.
`.claude/voice/voice.md` is the other thing, resident in every session because
`CLAUDE.md` imports it: how this team wants to be talked to. The two agree here,
this team's manner being a plain one, and they drift independently — a house
voice can be deliberately less plain and still want a way to ask for something
plainer. Neither tracks the other.
## Two invocations
- **Bare, at an answer that did not land.** Re-explain your own previous answer
as a causal chain in plain words. The operator is telling you the last one
failed, so a longer version of it fails again; what was missing is the *why*,
not the *more*.
- **With a question.** Answer that question under the rule, investigation
included — find the cause before writing, not after being asked twice.
Either way the output is an answer, not a plan to produce one.
## The pass
1. **Name what the answer rests on, or go find it.** A cause where something
happened, a reason where something was chosen, a constraint where something
could not be otherwise — the question decides which, and not every question
is about a malfunction. Then ask whether anything you can read settles it:
the history, the input, the configuration, the prompt. An answer written from
what the system printed is one written before the reading finished. When it
is genuinely unknowable, say so once, name what would settle it, and stop
there rather than filling the gap with evidence.
2. **Draft it somewhere you can re-read it, which here means thinking** —
conclusion first, in the nouns of the person affected, then the chain that
leads to it with each link saying why the next followed, then a concrete
example (§ "The example"), then the caveats if and only if they change what
the reader should do.
3. **Run the six defects below over that draft, then write it out again.** Each
has a tell you can see in your own text without knowing the subject — but only
in text you actually put down first.
## The example
**Show one concrete case of what the answer says, whatever the answer is
about.** A reader who lost the general statement usually follows a case, and
"give me a concrete example" is the question they would most often ask next.
The only answer that needs none is one already told as a scenario the reader
could replay — "this test fails because of that line" is not one yet.
- **The smallest thing that still shows it.** A few lines, two rows, one call and
what it returns — stripped of everything not carrying the point. Past that
size the reader is decoding the example instead of the idea.
- **Invented is fine, and often better.** A made-up `f()` or a toy table shows
the shape without the local detail a real case drags along. Use the real one
when the point is about that real thing.
- **It follows the conclusion, never replaces it.**
So a fix to a cache keyed only by the URL gets the scenario it broke: Alice
opens `/profile`, it is cached under `/profile`; Bob opens `/profile` and sees
Alice's.
## The six defects
They exist so a bad report can be called out in one word, the way `polar bear`
already works for `@.claude/skills/tend-prose/SKILL.md`. Read them as tells to
check a draft of your own against:
- | Defect | Tell |
- | --- | --- |
- | **Symptom-as-finding** | The headline is a quoted error string or a metric the system emitted |
- | **Buried lede** | Counts, windows, method notes or caveats before the conclusion |
- | **Untranslated nouns** | Jargon the reader does not use, where their own word exists and is exact |
- | **Broken chain** | Steps in sequence with nothing saying why each one followed |
- | **Fog** | Uncertainty stated repeatedly and never resolved into "here's what would settle it" |
- | **Receipt** | A reply *about* what the person said, where the thing they said wanted an answer — a joke acknowledged instead of returned, an aside filed instead of engaged |
+ - **Symptom-as-finding** — the headline is a quoted error string or a metric
+ the system emitted.
+ - **Buried lede** — counts, windows, method notes or caveats before the
+ conclusion.
+ - **Untranslated nouns** — jargon the reader does not use, where their own word
+ exists and is exact.
+ - **Broken chain** — steps in sequence with nothing saying why each one
+ followed.
+ - **Fog** — uncertainty stated repeatedly and never resolved into "here's what
+ would settle it".
+ - **Receipt** — a reply *about* what the person said, where the thing they said
+ wanted an answer — a joke acknowledged instead of returned, an aside filed
+ instead of engaged.
**The sixth is the odd one, and it earns its place by being the only one
investigation cannot fix.** The other five are cured by knowing more: read the
history, find the cause, say it in the right nouns. *Receipt* is cured by
answering the thing that was actually said. It is the same move as the rest one
level up, at the scale of a conversation rather than a report — narrating a
response instead of making it, which feels attentive and leaves the other person
unanswered. Its tell is the register shift: a neighboring sentence goes formal,
or refers to the remark in the third person ("noted", "a fair point", "I'll take
that on board").
Whether to return a joke at all is an operator entry — some people want the
deadpan. Acknowledging one instead of either returning it or passing it by is a
defect for everyone. The entry sets the register; the rule says don't hand
someone a receipt in place of a reply.
**A tell is a prompt to look again, not a verdict.** Someone who asks "what is
happening here??" has literally asked for a description, and a description
answers them; the question marks say they wanted it fixed. Which of the two
readings was owed is not always decidable, and nothing here decides it — what
the tell buys you is noticing that there were two.