---
name: n-llm-patch
description: >-
  Підготовка самодостатнього текстового промпта для іншого Claude/Cursor-агента —
  read-only аналіз CWD без жодних змін у поточному репо
---

<!-- markdownlint-disable-file MD024 MD025 -->
<!-- Файл демонструє шаблон промпта з кількома H1 (`# Завдання`, `# Релевантні файли` тощо)
     — це інтенціональна частина showcase, а не порушення one-title-per-document. -->

# Підготовка LLM-патчу (текстова комунікація між агентами)

Скіл готує **самодостатній текстовий промпт** ("патч") для іншої LLM-сесії
(Claude / Cursor agent у цільовому проєкті). Користувач копіює готовий блок
з відповіді чату й вставляє його в розмову з іншим агентом — той виконує
запитані зміни вже у своєму середовищі.

## Принципи

- **Read-only:** скіл нічого не пише в поточне репо. Лише читає CWD.
- **Тимчасові артефакти — лише в `/tmp`** (наприклад, `tree`-вивід чи
  проміжні чернетки промпту); ніколи не у CWD.
- **Цільова LLM:** Claude / Cursor agent — припускаємо, що читач знається
  на XML-тегах, file refs (`path/to/file.ts:42`), markdown.
- **Один блок виводу:** результат — це **один** markdown-блок у відповіді
  чату, готовий до копіювання.
- **Лаконічність — головне:** промпт містить **інтент + покажчики**, а не
  цитати + готовий код. Цільова LLM має повний доступ до свого CWD через
  `Read`/`Grep`/`Glob` і прочитає актуальний стан сама — наш патч не повинен
  дублювати те, до чого вона додумається з 2-3 файлів.

## Що **не** включати у промпт (cut list)

Цільова LLM сама прочитає файли — не дублюй їх. Викидай:

- **Великі цитати коду** з файлів, які LLM знайде за file ref. Замість блоку
  з 30 рядками функції — один рядок: `див. rules/foo/bar.mjs:120-150 (collect)`.
  Цитуй **тільки**: вже видалений код (тобто LLM його не знайде), або фрагмент
  з зовнішнього джерела (логи, stderr, помилка з CI).
- **Готові імплементації** ("ось як має виглядати новий `defaultRunner`")
  з повним кодом. Опиши інтент і обмеження — LLM напише код сама й краще
  під поточний стиль файлу. Виняток: один-два рядки, які важко описати словами
  (наприклад, точна назва прапора CLI).
- **Покрокові підказки рівня "крок 1: import X, крок 2: split into a) і b)…"**
  з псевдо-кодом. Це передчасна архітектура — описуй **бажану поведінку**
  (input → output, edge cases), а декомпозицію довір LLM.
- **Повний вміст `package.json`, конфігів, helpers** — досить імені поля та
  значення, що змінюється: `engines.node: ">=22" → ">=25"`. Якщо значення
  специфічне (peer ranges, exports map) — цитуй **тільки цей фрагмент**.
- **Огляд альтернатив, які ти відкинув,** із розгорнутими аргументами. Один
  рядок: "розглянутий варіант X відкинуто — Y" або взагалі прибрати, якщо
  LLM сама дійде того самого висновку.
- **Списки існуючих helpers ("вже є addCoverage у rules/test/coverage")** —
  досить рядка-покажчика; LLM зайде `Grep`'ом і прочитає сигнатуру сама.
- **Дублювання правил репо** (`CLAUDE.md`, `.cursor/rules/*.mdc`) — досить
  згадки "дотриматись n-test.mdc"; LLM прочитає файл сама.
- **Готовий `tree -L 2`-дамп** — досить рядка "монорепо з workspaces
  cf/_, run/_, gt (bun)"; повна структура майже завжди шум.
- **Самоочевидні acceptance-checks** ("тести зелені", "лінтер чистий") —
  пиши тільки специфічні до завдання ("на репо `ai`: `bun run coverage`
  не падає з `JS coverage exit 1`").

## Що **обов'язково** включити

- **Інтент** — 1-3 речення, що саме треба і чому (1 речення на причину).
- **Симптом / репро,** якщо це bugfix: справжній stderr, точна команда,
  exit code. Це **не** виводиться з коду — без нього LLM не знає, що
  саме ламається.
- **File refs** на ключові точки правки: `path:line` або `path:line-range`,
  з одним рядком пояснення кожна.
- **Реальні обмеження,** які не виводяться з коду: версії в репо-споживачі,
  inflight-міграції, breaking-change політика, зовнішні залежності.
- **Change-file flow,** якщо завдання змінює файли у пакетному workspace (код,
  правила, скіли, конфіги, тести — не лише `docs/`): промпт має вимагати
  `npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]`
  і `npx @nitra/cursor fix changelog`. **Ніколи** не інструктуй ручне редагування
  `CHANGELOG.md` чи bump `version` — це робить release flow / CI (деталь —
  `.cursor/rules/n-changelog.mdc`, не дублюй її текст). Якщо потрібна реліз-нота —
  це change-файл `<ws>/.changes/<timestamp>-<rand>.md` з `bump:` і `section:`,
  який створює саме `change` CLI, а не редагування файлу вручну.
- **Як перевірити** — конкретні команди й специфічні до завдання сигнали
  успіху.

## Виклик

```
/n-llm-patch <вільний опис завдання>
```

Аргумент має містити: **що треба зробити**, опційно — **назву пакета /
підмодуля** для контексту. Якщо аргумент порожній — попроси користувача
сформулювати завдання, не вгадуй.

Приклад:

```
/n-llm-patch підготуй для проекту @nitra/eslint-config щоб він врахував останню версію node
```

## Workflow

1. **Розпарсити аргумент** — виокремити суть завдання та (якщо є) назву
   пакета / шлях. Аргумент = намір користувача, передається у промпт
   як розділ "Завдання".

2. **Зібрати read-only контекст з CWD — мінімум, потрібний для опису
   інтенту й покажчиків:**
   - `package.json` — лише поля, релевантні до завдання (напр., для "node"
     — `engines`, `name`, `version`; для "eslint" — `peerDependencies`,
     `exports`). Не читай поля, які потім не з'являться у промпті.
   - Структура репо — швидкий огляд (`ls` верхнього рівня), щоб згадати
     **тип** ("монорепо bun з 7 workspaces" — рядком, не дампом).
   - **Релевантні файли** — відкривай саме ті, що потрібні щоб знайти
     `file:line` покажчики на точки правки. Не читай "про запас".
   - `CLAUDE.md` / `.cursor/rules/*.mdc` — лише **перевір наявність**
     і назви файлів-правил, які стосуються завдання (LLM прочитає сама).

3. **Визначити "точку патчу"** — 1-5 `path:line` покажчиків на місця, які
   найімовірніше треба правити, з одним рядком пояснення на кожен.

4. **Сформувати промпт за шаблоном нижче.** Цитуй код **тільки** коли він
   зовнішній (stderr, лог CI) або уже видалений. Існуючий код у CWD не
   цитуй — давай `path:line` ref.

5. **Прорахуй cut list:** перед видачею пройдись по секції "Що **не**
   включати" вище і видали все, що цільова LLM може отримати з 2-3
   `Read`/`Grep`-викликів у своєму CWD.

6. **Вивести один markdown-блок у чат** — без додаткових коментарів
   поза блоком, окрім однорядкового підпису "готово до копіювання".

## Шаблон вихідного промпта

Тільки секції, які несуть навантаження. Порожніх не залишай. Зразок:

````markdown
```markdown
# Завдання

<1-3 речення: що треба і яка причина (баг / новий стек / requirement).
Якщо bugfix — вкажи симптом одним рядком.>

# Симптом / репро

<тільки для bugfix: точна команда + ключовий рядок stderr/exit code.
Пропусти секцію, якщо не bugfix.>

# Точки правки

- `path/to/file.mjs:120` — <одне речення: що тут не так / що зробити>
- `path/to/other.mjs:34-50` — <…>

# Що треба зробити

<бажана поведінка input → output, edge cases, без псевдо-коду й
покрокових імплементаційних підказок. 3-8 буллетів.>

# Обмеження

<тільки реальні, не виводяться з коду: версії у репо-споживачі, breaking-change політика, inflight-міграції. Пропусти секцію, якщо їх нема.>

# Як перевірити

- `<команда>` — <специфічний до завдання сигнал успіху>
```
````

### Контр-приклад (так робити не треба)

- Секція `# Контекст проєкту` з name/version/stack/docs — LLM прочитає
  `package.json` сама за 1 виклик.
- `## Структура (skim)` з `tree -L 2` дампом — шум.
- `## package.json` з повним JSON — досить рядка про конкретне поле
  у `Що треба зробити` або `Обмеження`.
- `## <функція>` з 30 рядками існуючого коду — давай `path:line` ref
  у `Точки правки`.
- Покрокові підказки з кодом ("крок 1: import X, крок 2: split…") —
  опиши поведінку, код напише LLM.

## Правила

- **Мова промпту:** українська за замовчуванням; якщо аргумент англійською —
  можна англійською. Технічні терміни — англійською.
- **Обсяг:** прагни до **30-100 рядків**. Якщо вийшло більше — пройдись
  по cut list і викинь усе, до чого LLM додумається з кількох
  `Read`/`Grep`. Більше 150 рядків — майже завжди ознака, що ти цитуєш
  код, який LLM прочитає сама.
- **Без галюцинацій:** не вигадуй полів `package.json`, версій, шляхів,
  номерів рядків — лише те, що реально прочитав з CWD. Якщо чогось
  бракує — явно так і напиши ("`engines.node` відсутнє").
- **Без імперативного тону до користувача:** промпт адресований **іншому
  агенту**, не людині. Використовуй "зроби", "онови", "додай".
- **Без секцій-пустушок:** якщо немає `Обмежень` чи `Симптому` — пропусти
  секцію цілком.
- **Без ручного changelog/version у промпті:** не формулюй у виводі інструкції
  на кшталт "додати запис у `CHANGELOG.md`", "bump `version` вручну" чи
  "оновити `package.json#version`". Зміни у workspace фіксуються винятково
  через change-file flow (`npx @nitra/cursor change …` → `npx @nitra/cursor fix changelog`);
  `version`/`CHANGELOG.md` формує CI.
- **Не вмикай у промпт:** секрети, `.env`, `node_modules`, бінарні файли,
  довгі логи, дампи `tree`, повні JSON конфігів, цитати існуючих
  helpers/функцій з CWD.
- **Усе в одному блоці:** результат — це **один** ` ```markdown ` блок;
  ніяких додаткових міркувань поза ним (крім фінального підпису
  "готово до копіювання").

## Що скіл **не** робить

- Не завантажує tarball з npm registry, не клонує git-репозиторії.
- Не редагує жоден файл у поточному проєкті (і поза ним).
- Не виконує сам "патч" — лише готує промпт для іншого агента.
- Не оптимізує під Gemini / GPT — лише Claude / Cursor agent.

## Приклад виклику й результату

Виклик:

```
/n-llm-patch у @nitra/eslint-config підняти engines.node до >=25
```

Очікуваний вивід:

````markdown
```markdown
# Завдання

Підняти `engines.node` у `@nitra/eslint-config` з `>=22` до `>=25`,
переконатися що peer `eslint ^9` сумісний з Node 25.

# Точки правки

- `package.json:18` — `engines.node`

# Що треба зробити

- Підняти `engines.node` до `>=25`; якщо peer `eslint ^9` несумісний —
  підняти range.
- Зафіксувати зміну change-файлом (НЕ редагувати `CHANGELOG.md` чи `version`
  вручну): `npx @nitra/cursor change --bump minor --section Changed --message "engines.node >=25"`.

# Обмеження

- Дотриматись `.cursor/rules/n-js-lint.mdc` і `.cursor/rules/n-changelog.mdc`
  (зміни у workspace = change-файл, не ручний CHANGELOG/version bump).
- Якщо `eslint ^9` офіційно не підтримує Node 25 — підняти peer range.

# Як перевірити

- `bun test` — зелений
- `node -p "require('./package.json').engines.node"` → `>=25`
- `npx @nitra/cursor fix changelog` → exit `0`
```
````

```
готово до копіювання — встав у чат з агентом у цільовому проєкті
```
