
<!-- Общий фрагмент для всех ролей. Правьте здесь, а не в файле роли. -->

## Стандарт письма (для каждой роли, которая пишет документы)

Текст, который вы сдаёте, — часть результата. Стандарт распространяется на все
документы, которые вы создаёте: PRD, RFC, CONTEXT, PLAN, BRIEF, SPEC, README,
отчёт ревью, комментарий к бусине, — а не только на те, которые правит
технический писатель.

**Что проверяется автоматически.** Эти пункты выдаёт `beadloom lint`; не ждите,
пока он о них напомнит.

- **У цели есть измеримая формулировка.** «Сделать лучше» — не цель;
  «ядро сокращается с 440 строк до 376» — цель.
- **У решения есть причина, и причина объясняет «почему»**, а не пересказывает
  само решение. «Выбрали X, потому что X лучше» — не причина.
- **У риска есть конкретная мера снижения.** «Следить за этим» — не мера.
- **В утверждённом документе не остаётся открытых вопросов со статусом
  `Pending`.** План, утверждённый с нерешённым проектным вопросом, — это план,
  который ещё не составлен.
- **Ни один шаблонный placeholder не доживает до готового документа** —
  `[Name]`, `Criterion 1`, `TBD`. Артефакт, который создали по шаблону, который
  выглядит правильным и который никто не заполнил, — самая дорогая ошибка.

**Что не проверяется автоматически и всё равно обязательно.**

- **Открытый вопрос описывает обе стороны компромисса**, а не только выбранную.
  Раздел о том, что вне рамок, называет отвергнутый вариант **и причину отказа**.
- **Утверждения опираются на числа и на слово «измерено», а не на прилагательные.**
  «Намного быстрее» — не результат; «755 мс, измерено на полной переиндексации» —
  результат.
- **Никакой воды и никаких вводных оборотов** — ни канцелярита, ни извиняющихся
  или убеждающих вступлений к разделам. Заголовки нейтральные и описательные.
- **Полные предложения.** Не соединяйте два самостоятельных предложения точкой с
  запятой — напишите два предложения.
- **Единая терминология** внутри документа и однозначные местоимения.
- **Никаких калек и никаких обрезанных разговорных сокращений** — пишите слово
  целиком: «документация», а не «доки»; «репозиторий», а не «репо»;
  «конфигурация», а не «конфиг». Не переключайте язык внутри предложения:
  латиница — только для настоящих названий инструментов, методов и команд.
- **Каждое утверждение проверено по коду.** Описывайте то, что есть, а не то,
  что вы предполагаете.
- **Строки переносятся примерно на 95 колонке**, чтобы диф оставался читаемым.

**Язык документов — это конфигурация.** Он берётся из поля `language:` в
`.beadloom/flow.yml`, а не из этого файла и не из ваших предпочтений.
