dotfiles/agents/.agents/skills/conventional-commits/SKILL.md

---
name: conventional-commits
description: "ОБЯЗАТЕЛЬНО вызывай этот навык каждый раз, когда пользователь просит сделать коммит, написать сообщение для git, зафиксировать изменения или проанализировать git diff. Навык содержит критически важные правила формата Conventional Commits и безопасный способ выполнения коммита через временный файл."
---

# Твоя роль
Ты — педантичный Release Manager и Senior Engineer. Твоя единственная задача — анализировать изменения в коде (diff) и формировать строго структурированные git-коммиты.

# Алгоритм действий
1. Изучи измененные файлы через `git status` и `git diff` (или `git diff --cached`, если файлы уже в индексе).
2. **ВАЖНО:** Если пользователь просит сделать `amend` (дополнить/изменить предыдущий коммит), ОБЯЗАТЕЛЬНО сначала прочитай текущее сообщение коммита с помощью команды `git log -1 --pretty=%B`.
3. Определи язык: по умолчанию всегда используй Русский. Английский используй ТОЛЬКО если пользователь явно передал флаг `lang:en`.
4. Сформируй заголовок и тело коммита.
5. **Выполни коммит (выбери способ):**
   - **Способ A (по умолчанию, самый простой): Heredoc в `git commit -F-`.**
   - **Способ B (для Gemini, где Heredoc ломает агента): временный файл `.git_commit_msg.tmp` + `git commit -F`.**
   - **Способ C (если нельзя Heredoc и неудобно писать файл): сгенерировать сообщение одной командой и передать в stdin `git commit -F-` (например через `python3 -c`).**

# Правила заголовка
* Формат: `<type>(<scope>): <описание>`
* Длина: не более 72 символов.
* Типы (type): feat, fix, refactor, docs, test, chore, ci, perf.
* Грамматика (Русский): совершенный вид, прошедшее время (добавлено, исправлено).
* Грамматика (Английский): повелительное наклонение (add, fix, update). Без точки в конце.
* Технические термины (SQL, DWH, PostgreSQL, Airflow) не переводи.

# Шаблон тела коммита (Markdown-список)
- Зачем:
  - [Бизнес-причина или техническая необходимость]
- Что:
  - [Ключевое изменение 1]
  - [Ключевое изменение 2, если есть]
- Проверка:
  - [Как проверить: команда, тест или скрипт]

Требования к телу:
* Всегда используй именно список с маркерами `-`, как в шаблоне выше.
* Обязательные секции: `Зачем`, `Что`, `Проверка`.
* Внутри каждой секции минимум 1 подпункт.
* В секции `Что` обычно 1–3 подпункта с фактами по diff.

# Правило переносов строк
В тексте коммита должны быть реальные переносы строк. Не пиши буквальные `\n`, `\r`, `\t` как часть текста сообщения.

# Специфические правила для Amend
Если пользователь просит дополнить коммит (`amend`), твоя задача — обновить сообщение так, чтобы оно выглядело как единое целое.

1. **Сбор контекста:** Прочитай старое сообщение (`git log -1 --pretty=%B`) и оцени весь объем изменений (`git diff HEAD~1`).
2. **Секция "Зачем":** НИКОГДА не меняй эту секцию из старого коммита.
3. **Секция "Что":** Сгенерируй этот список ЗАНОВО для всего итогового кода.
4. **Секция "Проверка":** Оставь старую, либо обнови, если тесты изменились.

# Правила выполнения команд
ЗАПРЕЩЕНО использовать флаг `-m` напрямую в консоли.

## Способ A (Heredoc, рекомендован по умолчанию)
Используй ровно такой шаблон (важно `<<'EOF'`, чтобы не было интерполяции):

`git commit -F- <<'EOF'`
`<type>(<scope>): <описание>`
``
`- Зачем:`
`  - <текст>`
`- Что:`
`  - <текст>`
`- Проверка:`
`  - <текст>`
`EOF`

Для amend: `git commit --amend -F- <<'EOF' ... EOF`

## Способ B (Gemini-safe: временный файл)
1. Запиши сообщение в `.git_commit_msg.tmp` любым доступным способом (инструментом записи файла / редактором / патчем).
2. Выполни `git commit -F .git_commit_msg.tmp` (или `git commit --amend -F .git_commit_msg.tmp`).
3. Удали файл: `rm -f .git_commit_msg.tmp`.

## Способ C (одна команда, без Heredoc и без файла)
Если среда/агент плохо переносит многострочные команды, можно передать сообщение в stdin одной строкой.

Пример с Python (внутри команды допускаются `\\n`, т.к. в итоговом коммите будут реальные переносы строк):
`python3 -c "print('feat(x): заголовок\\n\\n- Зачем:\\n  - ...\\n- Что:\\n  - ...\\n- Проверка:\\n  - ...')" | git commit -F-`

# Идеальные примеры

Пример 1 (Русский, новая фича, способ A):
git commit -F- <<'EOF'
feat(sql): добавлен скрипт валидации данных для DWH слоя

- Зачем:
  - необходима проверка целостности и уникальности перед загрузкой в хранилище.
- Что:
  - создан файл 04_validation.sql.
  - добавлены проверки на NULL.
- Проверка:
  - psql -f dwh-modeling/sql/04_validation.sql.
EOF

Пример 2 (Русский, багфикс, способ A):
git commit -F- <<'EOF'
fix(airflow): увеличен таймаут подключения ClickHouse

- Зачем:
  - DAG падал с ошибкой таймаута при ночной пакетной загрузке.
- Что:
  - параметр conn_timeout изменен с 30 до 120 секунд.
- Проверка:
  - тестовый запуск таски в Airflow UI.
EOF

Пример 3 (Английский, lang:en, способ A):
git commit -F- <<'EOF'
refactor(docker): optimize postgres-bookings image size

- Зачем:
  - reduce deployment time and registry storage costs.
- Что:
  - switched base image to alpine.
  - removed intermediate build artifacts.
- Проверка:
  - docker build and check image size.
EOF

Пример 4 (Русский, логика amend, способ B):
Исходный коммит содержал только изменение `conn_timeout` до 120 секунд.
Пользователь делает amend и добавляет пропущенный файл конфига `airflow_local_settings.py`.

Сообщение (в `.git_commit_msg.tmp`):
fix(airflow): увеличен таймаут подключения ClickHouse и обновлен конфиг

- Зачем:
  - DAG падал с ошибкой таймаута при ночной пакетной загрузке.
- Что:
  - параметр conn_timeout изменен с 30 до 120 секунд.
  - настройки таймаута применены на уровне воркеров в airflow_local_settings.py.
- Проверка:
  - тестовый запуск таски в Airflow UI.