write git:20261102.d893fd0A

Immutable. This exact content never changes and is served at /api/v1/blob/e3db5e0bc2b42567.

---
name: write
description: >
  Письмо й правка технічного документа українською: контракт роботи перед
  письмом, профіль проєкту, жанрові правила (HLD, LLD, ADR, ТЗ, How-to/runbook,
  покрокова інструкція, Concept, Reference, Troubleshooting, постмортем, схема),
  дисципліна джерел і маркерів невизначеності, вилки й питання до суміжників,
  самоперевірка й закривальний рядок. Використовувати, коли пишеться або
  правиться текст технічного документа: новий документ чи розділ, правка,
  "напиши HLD", "переписати документ", "оформити як нотатку", "перекласти
  технічний текст українською", "ТЗ", "технічне завдання", "специфікація
  вимог", "покрокова інструкція", "степ бай степ", "step-by-step", схема до
  документа, питання до суміжного підрозділу, реєстр
  відкритих питань, а також коли інший скіл пакета за своїм результатом править
  текст. Не вмикатися на перевірку без правки ("перевір мову", "фактчекінг",
  "рецензія"), на збірку файла без зміни змісту ("зібрати docx") і на
  планування — це скіли language, factcheck, review, export, plan.
---

# Письмо технічних документів

Скіл пише й править текст. Дані проєкту — імена джерел, реєстр кодів, словник
термінів, палітри, профілі вивантажень — лежать у самому проєкті й
підключаються через **профіль проєкту**.

Файли називаються коротко. `language.md`, `evidence.md`, `genres/*.md` і
`templates/project-profile.md` лежать у спільній теці плагіна `../../shared/`
від теки цього скіла; `forks-and-questions.md`, `postmortem/*.md` і шаблони
постмортему — у `references/` і `templates/` цього скіла. Повна карта —
`../ukrainian-tech-docs/SKILL.md`, розд. 4.

## 1. Контракт роботи

Фіксується на вході, до першого рядка тексту. Це не план і не обговорення:
сім рядків, які виконавець називає сам і показує власникові. Заперечення
міняє рядок; відсутність заперечення лишає його чинним.

| Рядок | Що в ньому |
|---|---|
| Жанр | Називає власник на вході, або він виводиться з контексту: з назви документа, з теки, з того, що власник просить. Жанру не видно — одне питання, не здогад |
| Читач | Хто читатиме й що він уже знає. Від цього залежить, що пояснюється, а що ні |
| Вихід назовні | Лишається документ у сховищі проєкту чи йде читачеві поза командою. Другий випадок вмикає стадію вивантаження |
| Межа глибини | Для пари HLD/LLD — що лишається в цьому документі, а що йде в сусідній. **Виняток із межі записується тут**: «у цьому HLD значення X лишається в тілі, бо …». Виняток, не записаний у контракт, є дефектом, а не рішенням |
| Звідки наповнення | Джерела, з яких документ пишеться: ноти, файли, документація, стенд. Названий ресурс читається до того, як про нього писати |
| Не робимо | Що з теми в цей документ не йде. Формулюється перед входом у кожен розділ заново |
| Стадії | Які стадії пройде робота: рядки таблиці розд. 3 цього скіла й скіли пакета, які знадобляться (`language`, `factcheck`, `export`, `review`). Стадію визначає те, що відбувається з текстом, а не результат роботи: зміст змінюється — у переліку є Письмо й Самоперевірка; чистка мови без зміни змісту — скіл `language` (`../ukrainian-tech-docs/SKILL.md`, розд. 2). Наприкінці цей рядок звіряється із закривальним рядком (розд. 3) |

**Дрібна правка.** Для правки в межах одного абзацу без зміни змісту — описка,
правопис, розділовий знак, заміна слова — виконавець показує лише рядки «Жанр»
і «Стадії»; решта рядків діє за замовчуванням. Правка, що зачіпає твердження,
суб'єкт дії чи сусідній абзац, іде з повним контрактом. Правка, яку повертають
у розмові й не записують у сховище, переліків `evidence.md`, розд. 7, не
потребує: вони супроводжують запис.

Контракт живе в розмові. У документ він не пишеться, крім рядка «Не робимо»,
який за жанровим файлом може осідати в заготовці розділу.

Планування — окремий скіл `plan`, і письмо його **не пропонує**. Він вмикається
тільки за явним посилом власника.

## 2. Профіль проєкту

Профіль — один файл у проєкті, заповнений за `templates/project-profile.md`.
Він є точкою входу скіла в проєкт: скіл знає слоти, профіль каже, де в цьому
проєкті лежить їхній вміст.

| Слот | Що скіл із нього бере |
|---|---|
| Сходи джерел | Імена джерел на кожному із шести рівнів пошуку (`evidence.md`, розд. 2) |
| Реєстр кодів із колонкою опори | Які внутрішні коди існують і чи можна на код спиратись як на підставу (`evidence.md`, розд. 5) |
| Термінологія | Словник проєкту: які слова вживаються, яких уникають (`language.md`, частина 2) |
| Куди йдуть відкриті питання | Реєстр або ноти, куди переїжджає питання з адресатом (`forks-and-questions.md`) |
| Реєстр зовнішніх документів | Робочі адреси документів поза сховищем проєкту — для посилань у вивантаженні (`export.md`, розд. 3) |
| Профілі вивантаження | Перелік заповнених `export-profile` для конкретних файлів (`export.md`, розд. 6) |
| Палітри схем | Кольори, набори фігур, розміщення файлів схем (`genres/schema.md`) |
| Місце конвенції метаданих | Де лежать правила frontmatter, тегів, статусів. Скіл метаданих не визначає взагалі |
| Проєктні жанри | Жанри, описані лише в проєкті, і де вони лежать (розд. 3, «Перелік жанрів відкритий») |
| Правила комунікації | Звертання до кількох отримувачів, чи може лист бути першоджерелом факту, чи ставлять питання в коментарі трекера (`genres/general.md`, розд. 3 і 7) |
| Рецензія | Дані для скіла `review`: правила для рецензентів, субагенти, доменний експерт, минулі уроки, норма безпеки, вимоги, реєстри вже відомого (`templates/project-profile.md`, розд. 12) |
| Правила проєкту, старші за пакет | Місця, де проєкт свідомо відходить від правила пакета, з причиною. Записане тут — уже рішення; незаписана розбіжність іде за правилом «Старшинство» нижче |

**Порядок.** На вході знайти профіль: вказівник на нього стоїть в інструкціях
проєкту або в його кореневому файлі для агента. Знайшов — прочитати до контракту.

**Що таке вхід.** Вхід — момент, коли із запиту видно, що результатом буде документ,
його правка, аудит або вивантаження. Він раніше за розвідку: профіль і жанровий
файл читаються до матеріалу, бо саме вони кажуть, що в матеріалі шукати. Контракт
показується після розвідки — рядок «Звідки наповнення» без неї не заповнити, — але
до першого рядка тексту й до окреслення обсягу. Обсяг, окреслений до жанрового
файла, складається без межі глибини й без «Не робимо».

**Профілю немає.** Скіл працює на власних правилах, а кожне місце, де потрібен
вміст слота, називається вголос: «сходи джерел без імен — беру форму, імена
питаю». Такі питання йдуть одним пакетом з іншими питаннями цієї роботи
(`references/forks-and-questions.md`, розд. 9). Вигадувати вміст слота не можна.
Якщо робота в проєкті триває довше за один документ — один раз запропонувати
заповнити профіль за шаблоном.

**Старшинство.** Дані профілю старші за приклади скіла. Правило скіла старше
за звичку сусіднього документа. Розбіжність між правилом скіла й правилом
проєкту не розв'язується мовчки: показати обидві редакції і дочекатись рішення.

## 3. Стадії письма

Читається тільки те, що стоїть у рядках поточних стадій.

`language.md` довший за одне читання (понад 100 КБ): інструмент читання віддає
лише першу частину. Файл дочитується частинами до кінця, з наступного рядка
після прочитаного. Розділ, якого не дочитано, у рядку стадій не називається
пройденим.

**Стадії не взаємовиключні.** Робота рідко стоїть в одному рядку: вивантаження,
під час якого переписано зміст, — це ще й Письмо та Самоперевірка; аудит із
правкою — теж; фактчекінг, за яким правиться текст, — теж. Стадію визначає те,
що відбувається з текстом, а не назва результату. Зміст змінюється — Письмо
й Самоперевірка обов'язкові, яку б задачу не названо в запиті. Чистка мови без
зміни змісту — скіл `language` з його передумовами (`../ukrainian-tech-docs/SKILL.md`,
розд. 2). Жоден рядок
таблиці не замінює іншого.

**Правка вноситься одним заходом.** Спершу зібрати всі зміни й перевірити їх,
потім записати. Кілька записів поспіль, кожен з яких виправляє попередній,
означають, що перевірка йшла після запису, а не до нього.

**Зауваження до одного місця — сигнал перевірити весь текст.** Коли власник
вказує на ваду в одному реченні, той самий клас помилки шукати по всьому
документу: зміст, логіка, адресат вимоги, мова. Правка лише процитованого місця
лишає ту саму ваду поруч.

| Стадія | Коли | Читати |
|---|---|---|
| Вхід | перед першим рядком | цей файл · профіль проєкту · `genres/<жанр>.md` · `genres/general.md` — з кожним жанром |
| Письмо | пишеться або правиться текст | `evidence.md` · `language.md` · `genres/<жанр>.md` |
| Вилка | у тексті з'явився вибір, відкрите питання або звернення до суміжника | `forks-and-questions.md` |
| Схема | у розділі є предмет для схеми або схема правиться | `genres/schema.md` · слот палітр профілю |
| Самоперевірка | перед тим як вважати текст готовим | чек-лист у `genres/<жанр>.md` · фінальний прохід у `language.md` · розд. 7 `evidence.md` перед записом · ноти слотів реєстру кодів і термінології профілю — самі ноти, а не лише профіль, що на них вказує |

Інші задачі — окремі скіли пакета: перевірка мови й аудит без правки —
`language`, фактчекінг — `factcheck`, вивантаження назовні — `export`,
рецензія і тест читача — `review`, план — `plan`. Документ іде назовні —
після письма й самоперевірки викликати `export`; мовний прохід по остаточному
тексту він робить сам.

| Жанр | Файл | Що це |
|---|---|---|
| HLD | `genres/hld.md` | концепції, рішення, компроміси; без значень конкретної збірки |
| LLD | `genres/lld.md` | значення, адреси, параметри, порядок кроків як наслідок рішень HLD |
| ADR | `genres/adr.md` | одне архітектурне рішення з варіантами й компромісом |
| ТЗ | `genres/tz.md` | що потрібно і як це приймають; лише виконувані пункти, без маркерів і відкритих питань |
| How-to, runbook, процедура | `genres/howto.md` | кроки з перевіркою і відкатом; покриття розгортання і експлуатації |
| Покрокова інструкція | `genres/stepbystep.md` | лише дії для читача, який їх ще не виконував: пререквізити з перевіркою, крок за кроком, жодного твердження без джерела |
| Concept | `genres/concept.md` | як працює компонент |
| Reference | `genres/reference.md` | таблиці, схеми даних, коди; без прози |
| Troubleshooting | `genres/troubleshooting.md` | запис випадку: симптом першим |
| Постмортем | `genres/postmortem.md` | закриття інциденту після відновлення сервісу |
| Схема | `genres/schema.md` | топологія і механізм; читаність у друці |
| План | `genres/plan.md` | скіл `plan`, тільки за явним посилом |
| Усе інше | `genres/general.md` | правила для всіх жанрів; лист, нотатка, README, коментар у трекері задач |

**Перелік жанрів відкритий.** Жанр без власного файла працює на `general.md`.
Жанр, який існує тільки в одному проєкті, описується в самому проєкті,
і профіль на нього вказує; у пакет він іде тоді, коли знадобився в другому.

### Закривальний рядок і підсумок маркерів

Перед словом «готово», перед віддачею файла й перед записом у сховище виконавець
пише рядок стадій — які стадії пройдено і які файли на кожній прочитано:

`Стадії: вхід (write/SKILL, профіль, genres/hld) · письмо (evidence, language) · самоперевірка (чек-лист жанру, фінальний прохід, реєстр кодів, словник) · вивантаження (export, діагностика кальок)`

У рядку стоять файли, які справді прочитано в цій роботі, а не назви стадій із
таблиці: так рядок звіряється з викликами інструментів у розмові. Рядок
звіряється з рядком «Стадії» контракту. Стадії з контракту в рядку немає —
«готово» не пишеться: або стадію пройти, або назвати, чому її пропущено.

**Підсумок маркерів.** Поруч із рядком стадій іде перелік маркерів
`[на погодження]` і `[припущення]`, поставлених у цій роботі, по рядку на
маркер: де стоїть · що вирішено чи припущено · чия зона. Виконавець показує
перелік завжди, навіть порожній: «маркерів не ставив». Мовчання лишає
`[на погодження]` чинним для подальшої роботи, але не погодженим
(`forks-and-questions.md`, розд. 5), а `[припущення]` — твердженням, якого
ніхто не перевіряв: непоказаний маркер стає рішенням без погодження. На
вивантаженні `[на погодження]` без явної відповіді розкривається словами стану
(«Пропонується…», «Очікує погодження…») або йде у відкриті питання, а не
рішенням (`export.md`, розд. 4). Виняток — передача ТЗ у роботу: там мовчання не діє, і власник
закриває кожен рядок явно (`genres/tz.md`, розд. 2).

Підсумок іде разом із двома переліками `evidence.md`, розд. 7, і в тому самому
порядку: у сховище з історією змін запис іде одразу, а підсумок — у звіті
відразу після нього; запис назовні чекає відповіді на підсумок. `[припущення]`, уже внесене
в перелік тверджень без джерела, у підсумку вдруге не стоїть.

**Типи не змішуються в одному файлі.** Якщо в how-to з'явився розділ «Як це
працює всередині» — він виноситься в Concept, і ставиться посилання. Структура
тіла документа й поле жанру в метаданих проєкту — різні осі: значення поля
визначає конвенція метаданих проєкту, не цей пакет.

## 4. Чого пакет не робить

- Не визначає метаданих: frontmatter, теги, статуси, нумерацію — це конвенція проєкту.
- Не пропонує планування і не вмикає його сам.
- Не тримає даних проєкту: імен джерел, кодів, палітр, адрес. Приклади у файлах — приклади.
- Не застосовується до художніх текстів.

## 5. Склад скіла

```
SKILL.md
references/
  forks-and-questions.md    вилки, питання до суміжників, реєстри питань
  postmortem/               довідники до жанру постмортему
templates/
  postmortem-template.md    шаблон постмортему
  action-item-tracker.md    трекер дій після постмортему
../../shared/
  evidence.md               джерела, маркери, коди, перелік перед записом
  language.md               мова, терміни, аудит, фінальний прохід
  genres/                   hld · lld · adr · tz · howto · stepbystep · concept · reference ·
                            troubleshooting · postmortem · schema · plan · general
  templates/project-profile.md   шаблон профілю проєкту
```