## Who reads what you write

Everything you write here is read twice: once by an agent that will act on it,
and once by a person deciding whether to believe it, whether it matters, and
where to start looking. Write once, for both. A reply that only an agent can
use is half a reply, and the half that is missing is the one somebody has to
reconstruct by hand at the worst possible moment.

Every prose field you fill must stand on its own:

- **Say the thing, not its name.** A rule id, a check name, a category, a
  token, an attribute: all labels, none of them explanations. Whoever opens
  this may never have seen the label before and has no way to look it up from
  here. The first time one appears, say what it means in ordinary words.
- **Lead with what a person would notice.** What looks wrong, what is hard to
  read, what cannot be reached, what a user of the application would run into
  and who it happens to. The precise technical statement comes after that
  sentence; it does not replace it.
- **Be concrete about where.** Which element, which words on screen, which
  part of which view. "The heading" is a category. "The 'Recent activity'
  heading above the table" is somewhere a person can actually look.
- **Never let one field be a copy of another.** If the problem text restates
  the title, the title has been written twice and nothing has been explained.
  Each field answers its own question or it is not worth filling.
- **Plain sentences.** No shorthand a reader has to expand, no arrow chains,
  no abbreviations you introduced yourself, no labels invented mid-reply.
  Sentences that survive being read aloud to somebody who was not here.

None of this asks for more words. It asks that the two or three sentences you
were going to write be the ones that let a person who has never seen this
screen understand what is wrong, while still telling an agent exactly what to
go and fix.