git:20261030.553e302 to git:20261102.afe4486

- Пакет письма технічної документації українською: контракт роботи перед письмом,

- дисципліна джерел і маркерів невизначеності, жива мова без ШІ-кліше, жанрові

- правила (HLD, LLD, ADR, ТЗ, How-to/runbook, покрокова інструкція, Concept,

- Reference, Troubleshooting,

- постмортем, схема, план), вилки й питання до суміжників, вивантаження назовні

- (.docx, .xlsx, .pdf, лист). Використовувати завжди, коли користувач пише, редагує,

- перевіряє або вивантажує будь-який технічний документ українською, малює схему

- до нього, формулює питання до суміжного підрозділу чи реєстр відкритих питань,

- а також на прохання "переписати документ", "почистити текст", "прибрати воду",

- "оформити як нотатку", "зібрати docx", "перекласти технічний текст українською",

- "діагностика кальок", "перевір переклад", "фактчекінг", "перевір факти",

- "звір із документацією", "тест читача", "чи зрозуміло це без мене", "ТЗ",

- "технічне завдання", "специфікація вимог", "перевір ТЗ", "покрокова інструкція",

- "степ бай степ", "step-by-step".

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

-

- Пакет несе все, що працює безвідносно проєкту й користувача. Дані проєкту —

- імена джерел, реєстр кодів, словник термінів, палітри, профілі вивантажень —

- лежать у самому проєкті й підключаються через **профіль проєкту**.

- Цей файл несе три речі: контракт роботи, таблицю «стадія × жанр → файл» і правило

- роботи з профілем. Зміст правил лежить у `references/` і читається за таблицею,

- а не цілком.

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

- Фіксується на вході, до першого рядка тексту. Це не план і не обговорення:

- сім рядків, які виконавець називає сам і показує власникові. Заперечення

- міняє рядок; відсутність заперечення лишає його чинним.

- | Рядок | Що в ньому |

- |---|---|

- | Жанр | Називає власник на вході, або він виводиться з контексту: з назви документа, з теки, з того, що власник просить. Жанру не видно — одне питання, не здогад |

- | Читач | Хто читатиме й що він уже знає. Від цього залежить, що пояснюється, а що ні |

- | Вихід назовні | Лишається документ у сховищі проєкту чи йде читачеві поза командою. Другий випадок вмикає стадію вивантаження |

- | Межа глибини | Для пари HLD/LLD — що лишається в цьому документі, а що йде в сусідній. **Виняток із межі записується тут**: «у цьому HLD значення X лишається в тілі, бо …». Виняток, не записаний у контракт, є дефектом, а не рішенням |

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

- | Не робимо | Що з теми в цей документ не йде. Формулюється перед входом у кожен розділ заново |

- | Стадії | Які рядки таблиці розд. 3 пройде робота. Стадію визначає те, що відбувається з текстом, а не результат роботи: текст змінюється — у переліку є Письмо й Самоперевірка. Наприкінці цей рядок звіряється із закривальним рядком (розд. 3) |

- **Дрібна правка.** Для правки в межах одного абзацу без зміни змісту — описка,

- правопис, розділовий знак, заміна слова — виконавець показує лише рядки «Жанр»

- і «Стадії»; решта рядків діє за замовчуванням. Правка, що зачіпає твердження,

- суб'єкт дії чи сусідній абзац, іде з повним контрактом. Правка, яку повертають

- у розмові й не записують у сховище, переліків `evidence.md`, розд. 7, не

- потребує: вони супроводжують запис.

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

- який за жанровим файлом може осідати в заготовці розділу.

- Планування — окрема стадія, і скіл її **не пропонує**. Вона вмикається тільки

- за явним посилом власника; тоді читається `references/genres/plan.md`.

- ## 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) |

- | Правила проєкту, старші за пакет | Місця, де проєкт свідомо відходить від правила пакета, з причиною. Записане тут — уже рішення; незаписана розбіжність іде за правилом «Старшинство» нижче |

-

- **Порядок.** На вході знайти профіль: вказівник на нього стоїть в інструкціях

- проєкту або в його кореневому файлі для агента. Знайшов — прочитати до контракту.

-

- **Що таке вхід.** Вхід — момент, коли із запиту видно, що результатом буде документ,

- його правка, аудит або вивантаження. Він раніше за розвідку: профіль і жанровий

- файл читаються до матеріалу, бо саме вони кажуть, що в матеріалі шукати. Контракт

- показується після розвідки — рядок «Звідки наповнення» без неї не заповнити, — але

- до першого рядка тексту й до окреслення обсягу. Обсяг, окреслений до жанрового

- файла, складається без межі глибини й без «Не робимо».

-

- **Профілю немає.** Скіл працює на власних правилах, а кожне місце, де потрібен

- вміст слота, називається вголос: «сходи джерел без імен — беру форму, імена

- питаю». Такі питання йдуть одним пакетом з іншими питаннями цієї роботи

- (`references/forks-and-questions.md`, розд. 9). Вигадувати вміст слота не можна.

- Якщо робота в проєкті триває довше за один документ — один раз запропонувати

- заповнити профіль за шаблоном.

-

- **Старшинство.** Дані профілю старші за приклади скіла. Правило скіла старше

- за звичку сусіднього документа. Розбіжність між правилом скіла й правилом

- проєкту не розв'язується мовчки: показати обидві редакції і дочекатись рішення.

-

- ## 3. Стадія × жанр → файл

-

- Читається тільки те, що стоїть у рядках поточних стадій. Шляхи — від `references/`.

-

- **Стадії не взаємовиключні.** Робота рідко стоїть в одному рядку: вивантаження,

- під час якого переписано зміст, — це ще й Письмо та Самоперевірка; аудит із

- правкою — теж; фактчекінг, за яким правиться текст, — теж. Стадію визначає те,

- що відбувається з текстом, а не назва результату. Текст змінюється — Письмо

- й Самоперевірка обов'язкові, яку б стадію не названо в запиті. Жоден рядок

- таблиці не замінює іншого.

-

- **Правка вноситься одним заходом.** Спершу зібрати всі зміни й перевірити їх,

- потім записати. Кілька записів поспіль, кожен з яких виправляє попередній,

- означають, що перевірка йшла після запису, а не до нього.

-

- **Зауваження до одного місця — сигнал перевірити весь текст.** Коли власник

- вказує на ваду в одному реченні, той самий клас помилки шукати по всьому

- документу: зміст, логіка, адресат вимоги, мова. Правка лише процитованого місця

- лишає ту саму ваду поруч.

-

- | Стадія | Коли | Читати |

- |---|---|---|

- | Вхід | перед першим рядком | цей файл · профіль проєкту · `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` перед записом · ноти слотів реєстру кодів і термінології профілю — самі ноти, а не лише профіль, що на них вказує |

- | Аудит чужого тексту | перевірка готового документа без правки; «переписати», «почистити», «прибрати воду» — замовлена чистка, поріг S2 її не блокує (`language.md`, «Вага ознак») | `language.md`, розділ «Аудит» · `genres/general.md`, розд. 5 · `genres/<жанр>.md` · перевірка мови — ще `language.md`, розділ «Діагностика кальок», окремим блоком звіту або рядком «не проходив» |

- | Тест читача | «тест читача», «чи зрозуміло це без мене»; одним рядком пропонується перед вивантаженням читачеві поза командою, сам не вмикається; нічого не править | `genres/general.md`, розд. 6 |

- | Діагностика кальок | «діагностика кальок», «перевір переклад», фінальний прогін мови по готових документах; нічого не править, повертає таблицю підозр на вердикт власника | `language.md`, розділ «Діагностика кальок» · слоти термінології і реєстру кодів профілю · `genres/schema.md`, розд. 3 — якщо в документа є схеми |

- | Фактчекінг | «фактчекінг», «перевір факти», «звір із документацією», «чи це досі так»; нічого не править, повертає таблицю тверджень на вердикт власника; виняток — покрокова інструкція (`genres/stepbystep.md`, розд. 7) | `factcheck.md` · `evidence.md`, розд. 1–3 · слоти сходів джерел і реєстру кодів профілю |

- | Вивантаження | документ іде назовні: `.docx`, `.xlsx`, `.pdf`, лист, повідомлення | `export.md` · профіль вивантаження з проєкту, якщо він є · для `.docx`, `.xlsx`, `.pdf` — мовний прогін перед збіркою (`export.md`, розд. 0): `language.md`, розділи «Діагностика кальок» і «Фінальний прохід» |

- | Планування | тільки за явним посилом власника | `genres/plan.md` |

-

- | Жанр | Файл | Що це |

- |---|---|---|

- | 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` | тільки за явним посилом |

- | Усе інше | `genres/general.md` | правила для всіх жанрів; лист, нотатка, README, коментар у трекері задач, аудит готового документа |

-

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

- Жанр, який існує тільки в одному проєкті, описується в самому проєкті,

- і профіль на нього вказує; у пакет він іде тоді, коли знадобився в другому.

- ### Закривальний рядок

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

- пише рядок стадій — які стадії пройдено і які файли на кожній прочитано:

- `Стадії: вхід (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/

- evidence.md джерела, маркери, коди, перелік перед записом

- factcheck.md фактчекінг готового тексту

- language.md мова, терміни, аудит чужого тексту

- export.md вивантаження назовні

- forks-and-questions.md вилки, питання до суміжників, реєстри питань

- genres/ hld · lld · adr · tz · howto · stepbystep · concept · reference ·

- troubleshooting · postmortem · schema · plan · general

- postmortem/ довідники до жанру постмортему

- templates/

- project-profile.md шаблон профілю проєкту

- export-profile.md шаблон профілю вивантаження для конкретного файлу

- postmortem-template.md шаблон постмортему

- action-item-tracker.md трекер дій після постмортему

- ```

-

- ## 6. Джерела пакета

-

- Готові скіли й статті, з яких узято ідеї. Текст пакета написано наново

- українською; англомовні правила перенесено лише там, де вони працюють для

- української мови.

-

- - humanizer, MIT: [blader/humanizer](https://github.com/blader/humanizer) —

- ознаки ШІ-тексту для частини 1 `language.md` і перевірка «що тут досі звучить

- як ШІ» і питання, що додано чи втрачено після правки; англійську специфіку

- (тире, регістр заголовків, лапки) як ознаки ШІ не перенесено. Регістр заголовків

- і лапки записано окремо, як норму правопису (`genres/general.md`, розд. 1). Залишки чату, заголовок,

- повторений першим реченням, і текст про документ замість предмета —

- [SKILL.md, §22, §24, §25](https://github.com/blader/humanizer/blob/225a6f3/SKILL.md)

- (`language.md`, 1.13).

- - humanizer, форк, MIT: [brandonwise/humanizer](https://github.com/brandonwise/humanizer).

- - Українські адаптації humanizer, усі MIT, узято лише ідеї, текст власний:

- [iosipov27/ukrainian-humanizer](https://github.com/iosipov27/ukrainian-humanizer) —

- голос автора перед чисткою (`language.md`, «Переписування зберігає зміст»);

- [asaulyuk/humanizer-ukr](https://github.com/asaulyuk/humanizer-ukr) — активні

- дієприкметники (1.7), канцелярит й аналітичний ступінь порівняння (1.4), кличний

- відмінок і типографіка (`genres/general.md`, розд. 1, 3), невидимі символи

- (`export.md`, розд. 0);

- [tatet-ua/tatet-humanizer](https://github.com/tatet-ua/tatet-humanizer) —

- службові мітки чату (1.13), хвостове заперечення (1.9), прийоми самої чистки;

- [majlovskij-cmd/humanizer-ua](https://github.com/majlovskij-cmd/humanizer-ua) —

- приклади кальок із російської («Діагностика кальок»);

- [OpenMindUA/SimpleUkrainian](https://github.com/OpenMindUA/SimpleUkrainian) —

- умова перед дією (`genres/howto.md`, розд. 2), висновок першим

- (`genres/general.md`, розд. 1), слова-порожнеча (1.4). Заборону тире, числові

- пороги, «додавай голос» і автозаміни «слово → слово» не перенесено.

- - technical-writer, MIT: [riekelt/technical-writer](https://github.com/riekelt/technical-writer) —

- контрольні питання після переписування: зміст не втрачено, прийом не

- повернувся в іншій формі (`language.md`, «Переписування зберігає зміст»).

- - humanizer-zh, MIT: [op7418/humanizer-zh](https://github.com/op7418/humanizer-zh) —

- те саме для китайської; підтвердження, що перевірка змісту після чистки

- потрібна незалежно від мови.

- - korean-humanizer з k-skill, MIT:

- [nomadamas/k-skill, `korean-humanizer/instruction.md`](https://github.com/nomadamas/k-skill/blob/50d7bb3/korean-humanizer/instruction.md) —

- рівні ваги ознак S1/S2/S3 і сортування «лише форматування — правити лише

- форматування» (`language.md`, «Вага ознак»). Розкладку пунктів по рівнях

- складено наново для української.

- - StoryScope: J. Russell et al., «StoryScope: Investigating idiosyncrasies in AI

- fiction», COLM 2026, [arXiv 2604.03136](https://arxiv.org/abs/2604.03136) —

- підтвердження, що окрема ознака ШІ не доводить, а сигнал дає їх поєднання

- (рівень S3).

- - J. Liao et al., «Defensive Writing in GPT Models», препринт, 2026,

- [arXiv 2610.11355](https://arxiv.org/abs/2610.11355v2) — застереження без

- підстави, які модель дописує, коли перевіряє твердження (`language.md`,

- «Переписування зберігає зміст»). Знайдено через

- [Nanako0129/sepia](https://github.com/Nanako0129/sepia), MIT, де на цій основі

- зроблено правило для переписування ділового тексту; текст правила власний.

- - Compound Engineering, MIT:

- [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) —

- ідея плану перед роботою (`/ce-plan`).

- - Matt Van Horn, «Every Agentic Engineering Hack I Know», 2026 — той самий

- підхід «спершу план», через статтю.

- - doc-coauthoring з anthropics/skills, ліцензію в репозиторії не визначено, узято лише ідею:

- [SKILL.md, Stage 3](https://github.com/anthropics/skills/blob/dbd4588/skills/doc-coauthoring/SKILL.md) —

- тест читача свіжим субагентом (`genres/general.md`, розд. 6).

- - wai-skill-suite, MIT:

- [woldinius/wai-skill-suite, `wai-requirements-planning`](https://github.com/woldinius/wai-skill-suite/blob/d83acaf/.claude/skills/wai-requirements-planning/SKILL.md)

- і [`grilling-protocol.md`](https://github.com/woldinius/wai-skill-suite/blob/d83acaf/.claude/skills/wai/references/grilling-protocol.md) —

- перелік припущень наприкінці роботи (розд. 3, «Підсумок маркерів»), пошук

- фактів у фоні й найменший варіант серед альтернатив (`forks-and-questions.md`,

- розд. 2–3), три виходи знахідки й формат кількох питань із рекомендацією, де залежне

- питання чекає (там само, розд. 8–9), термін із розмови — у словник проєкту

- (`language.md`, 2.1), дельта плану з датою

- (`genres/plan.md`, розд. 3) і поріг для ADR (`genres/adr.md`). Жорсткий стоп

- перед кожним кроком до підтвердження і питання без ліміту не перенесено: вони суперечать правилу

- «маркер замість питання».

- - mattpocock/skills, MIT: [`domain-modeling/ADR-FORMAT.md`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/domain-modeling/ADR-FORMAT.md) —

- три умови порогу ADR і класи рішень, які варто записувати (`genres/adr.md`);

- [`to-tickets`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/to-tickets/SKILL.md) —

- міграція зі співіснуванням у три кроки (`genres/howto.md`, розд. 3).

- - knowledge-work-plugins, Apache-2.0:

- [anthropics/knowledge-work-plugins, `engineering`](https://github.com/anthropics/knowledge-work-plugins/tree/main/engineering) —

- розділ «Коли застосовувати» в runbook (`genres/howto.md`, розд. 1) і умова

- перегляду рішення в «Наслідках» ADR (`genres/adr.md`).

- - archify, MIT: [tt-a1i/archify, `authoring-contract.md`](https://github.com/tt-a1i/archify/blob/d0c8c7e/archify/references/authoring-contract.md) —

- лінія крізь чужий вузол як помилка, підпис зв'язку не видаляють, порядок

- перевірки, рамка лише для справжньої межі, застарілі ручні маршрути

- (`genres/schema.md`, розд. 3). Сам інструмент не перенесено: він малює HTML

- через Node.js, а правила тут — для будь-якого інструмента.

- - Будова жанру ТЗ (`genres/tz.md`) зведена з кількох шаблонів специфікацій, MIT:

- [github/spec-kit](https://github.com/github/spec-kit) — сталі номери вимог,

- вимірювані критерії, граничні випадки;

- [automazeio/ccpm](https://github.com/automazeio/ccpm) — нефункціональні вимоги

- окремим блоком, припущення і обмеження;

- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — вимога у формі

- зобов'язання з умовою приймання;

- [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) —

- трасування вимоги до рішення і перевірки;

- [addyosmani/agent-skills, `spec-driven-development`](https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development) —

- межі виконавця в три яруси;

- [mattpocock/skills, `to-spec`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/to-spec/SKILL.md) —

- ухвалені рішення Замовника серед обмежень специфікації. Користувацькі історії як

- обов'язкову форму вимог, оцінку трудомісткості й зупинку на погодження перед

- кожною фазою не перенесено. Правило виконуваності — жодного маркера чи

- відкритого питання в ТЗ, переданому в роботу, — власне.

- - Окремі ідеї взято з README інших публічних скілів; текст власний.