git-report-skill/SKILL.md

---
name: git-report
description: Генерирует аналитический отчёт о прогрессе в Git-репозитории за период, анализируя коммиты, задачи и активность участников. Использует LLM для осмысленного описания изменений.
---

# Навык: git-report – Аналитический отчёт по репозиторию

## Назначение
Навык собирает данные о коммитах, задачах (issues) и пул-реквестах (PRs) за указанный период, а затем на основе этих данных формирует **содержательный отчёт о прогрессе**, написанный естественным языком. В отчёте отражаются:
- Ключевые изменения и их смысловая нагрузка (что сделано, зачем).
- Активность участников (кто, сколько и что делал).
- Выполнение задач и соответствие дедлайнам (если информация есть в issues).
- Общая оценка прогресса и рекомендации.

## Как использовать
Пользователь пишет агенту, например:
> "Сделай git-report для https://github.com/owner/repo за последние 2 недели"
> "Проанализируй прогресс в проекте https://gitlab.com/group/project за март 2026"

Если период не указан – анализируются **все изменения за всю историю** репозитория (от первого коммита до последнего).

## Порядок действий агента (строго!)
1. Извлеки из запроса URL репозитория и временной период (если не указан – анализируется вся история).
2. Выполни скрипт `scripts/generate_report.py`, передав аргументы:
   - `--repo-url` (URL)
   - `--since` (дата начала, YYYY-MM-DD) – если период указан
   - `--until` (дата конца, YYYY-MM-DD) – если период указан
   Скрипт соберёт данные и сохранит их в файл `/app/hermes_data/git_reports/<repo>_data.json`.  
   **Важно:** Теперь JSON содержит для каждого коммита не только сообщение и автора, но и список изменённых файлов (`files_changed`), количество добавленных (`insertions`) и удалённых (`deletions`) строк. Если период не задан, скрипт автоматически переключается на локальное клонирование и анализирует всю историю (это может занять больше времени, но даст полную картину).
3. **Прочитай этот JSON-файл** – в нём содержится вся собранная информация (коммиты, issues, PRs) в структурированном виде.
4. **Проанализируй данные** и напиши отчёт в формате Markdown. Отчёт должен включать:
   - **Общий прогресс** (количество коммитов, задач, участников).
   - **Содержательный разбор изменений** – сгруппируй изменения по темам (новые функции, исправления, рефакторинг, документация и т.д.) и укажи, кто, когда и что именно сделал. Не копируй комментарии коммитов, а сформулируй суть и смысл изменений человеческим языком на русском, исходя из комментария и содержания коммита. Используй данные о файлах и количестве изменённых строк, чтобы оценить масштаб работ.
   НЕ КОПИРУЙ комментарии к коммитам. ТЫ ДОЛЖЕН сам НА РУССКОМ сформулировать суть изменений. Если коммитов, относящихся по смыслу к одному изменению, много - объедини их в один пункт. Этот раздел является ГЛАВНЫМ
   в отчёте. Удели ему ОСОБОЕ ВНИМАНИЕ, хорошо формулируя смысл проделанной участниками работы. Эта та часть, на которую В ПЕРВУЮ ОЧЕРЕДЬ будет смотреть руководство при оценке прогресса команды в работе. Указывай даты выполнения работ и авторов.
   Для КАЖДОГО блока изменений укажи тех, кто принимал участие в работе и сроки проведения работы.
   В этой части не копируй метаданные и сухую статистику коммитов. В каждом блоке должны быть указаны авторы и сроки выполнения, далее - исключительно описание человеческим языком сути проделанной работы, без сухой статистики. Не надо перечислять изменённые файлы, количество строк и т.п. - только смысловое описание.
   - **Активность участников** – кто внёс какой вклад, какие задачи закрыл.
   - **Выполнение задач** – перечисли открытые/закрытые issues (если есть сведения), укажи, соблюдены ли сроки (если в issue есть метки с датами или дедлайнами).
   - **Оценка прогресса** – достигнуты ли цели периода, есть ли риски, насколько эффективной и соответствующей поставленным задачам и срокам была работа с учётом активности участников.
   - **Рекомендации** (если уместно).
   Отчёт должен по стилю соответствовать отчёту по прогрессу в IT-компании (НЕ ИСПОЛЬЗУЙ эмодзи и т.п.). Содержательный отчёт должен включать не просто перечень коммитов, а сведения об их смысле: что было добавлено/изменено, какая задача/работа выполнена (ты должен сам понять и сформулировать это по комментарию и содержанию коммита, а не просто скопировать комментарий).
5. Сохрани написанный отчёт в файл `/app/hermes_data/git_reports/<repo_name>_report.md`.
6. Сообщи пользователю путь к отчёту и краткую выжимку.

## Важные требования
- При анализе смысла коммитов учитывай diff.
- Тщательно следи за корректностью оформления и форматирования отчёта и переносов строк
- **Ни в коем случае не используй сухую статистику как готовый отчёт.** Ты должен переработать данные в связный текст.
- Если данных слишком много (например, сотни коммитов), агрегируй их (сгруппируй по смыслу, не перечисляй каждый коммит).
- Если в данных есть ссылки на дедлайны (например, в описании issue указано "срок: 2026-04-20"), обязательно проверь, выполнено ли вовремя.
- Используй профессиональный, но понятный стиль. Отчёт должен быть полезен для руководителя или команды.
- **НИ В КОЕМ СЛУЧАЕ** не придумывай те сведения, которых нет – только делай выводы из существующих данных.
- При анализе коммитов обращай внимание на поле `files_changed`, `insertions` и `deletions` – это поможет понять масштаб изменений (например, «крупный рефакторинг затронул 15 файлов» или «добавлено 500 строк кода в новом модуле»).
- Отчёт должен по стилю соответствовать отчёту по прогрессу в IT-компании
- **НИ В КОЕМ СЛУЧАЕ НЕ ИСПОЛЬЗУЙ** в отчёте эмодзи и иные подобные символы.
- Отчёт должен соответствовать официальному стилю отчёта и быть информативным
- Оформление отчёта должно соответствовать допустимому для официального в IT компании
- **НЕ КОПИРУЙ** в содержательный разбор изменений комментарии коммитов. Ты должен сам человеческим языком на русском сформулировать смысл коммита.
- **НЕ ДЕЛАЙ** в содержательном разборе сухой список коммитов. Ты должен сам проанализировать, какие изменения были внесены.

## Примечания
- Убедись, что скрипт имеет права на выполнение, а зависимости установлены (см. `requirements.txt`).
- Для доступа к API некоторых хостингов могут потребоваться токены (переменные окружения `GITHUB_TOKEN`, `GITLAB_TOKEN`). Если их нет, скрипт использует локальное клонирование (только коммиты, без issues).
- Если скрипт не смог получить issues/PRs (нет токена или API недоступен), работай только с коммитами – этого достаточно для базового отчёта.
- **Для анализа всей истории репозитория** (без указания дат) скрипт автоматически использует локальное клонирование, что даёт полную информацию о каждом коммите. Это может занять время, но результат будет максимально детальным.