update-docs

name	update-docs
description	Используй по просьбе: «обнови документацию», «обнови документацию для <path>», «обнови MODULE_INDEX.md»

Синхронизация документации

Overview

Синхронизация описания модулей с кодом: file headers, docs/<category>/<module>.md, MODULE_INDEX.md.

Mapping: каталог кода → docs/

Каталог кода	docs/
processing/	docs/processing/
statistics/	docs/statistics/
API/	docs/API/ (ML-сигнальные интеграции — также docs/MT/)
ML/	docs/ML/
MT/MQL4/	docs/MT/
tests/	docs/tests/

Примечание: изменение полей фрактала в lib_PIC.mqh → также docs/schemas/ (контракт MT4↔Python).

Шаблон file header

Python (.py)

Единый канон — русский. Базовые поля обязательны, расширенные — опциональны для инфраструктуры с нетривиальными зависимостями (processing/, ML/data_loader.py, ML/train.py):

# =============================================================================
# Файл: [filename.py]
# Назначение: [одна строка]
# Язык: Python 3.10+              # опционально
# Автор: [имя]                    # опционально
# Создан: [YYYY-MM-DD]            # опционально
# Обновлён: [YYYY-MM-DD]
# Зависимости:                    # опционально, для нетривиальных связей
#   Входные данные:
#     - [путь/файл] (откуда: [источник])
#   Выходные данные:
#     - [путь/файл] (куда: [назначение])
#   Внутренние зависимости:
#     - [module.py] (функция ...)
#   Внешние зависимости:
#     - [пакет]>=версия
# Использование:
#   python [filename.py] [аргументы]
# Примечания:                     # опционально
#   - [важные ограничения]
# =============================================================================

Английский compact-header (File:/Purpose:) не переделывать без необходимости.

Обновлять header при изменении: назначения, входов/выходов, CLI. Не обновлять при рефакторинге внутренней логики.

MQL4 (.mqh / .mq4) — только если есть #include-связь с задачей

Box-стиль (большинство .mqh):

//+------------------------------------------------------------------+
//| Файл: [filename.mqh]                                             |
//| Назначение: [одна строка]                                        |
//| Обновлён: [YYYY-MM-DD]                                           |
//| Зависимости: [файл.mqh]                                          |
//+------------------------------------------------------------------+

Doxygen //!-стиль также встречается (например lib_PIC.mqh) — не переделывать. Кодировка .mqh/.mq4 в репо — UTF-8 (с кириллицей); Проверяй file перед правкой.

Docstrings (Google Style)

Писать: публичные функции с нетривиальной логикой, все классы, публичные методы. Не писать: приватные хелперы (_foo), функции с говорящим именем и ≤3 строками тела. Описание shape массивов обязательно: shape (N, 20).

def compute_quantile_score(predictions: np.ndarray, threshold: float) -> np.ndarray:
    """Вычисляет бинарный сигнал по квантильному порогу.

    Аргументы:
        predictions: Массив предсказаний, shape (N,).
        threshold: Квантильный порог [0.0, 1.0].

    Возвращает:
        Бинарный массив сигналов shape (N,), 1 = активная позиция.
    """

Классы — аналогично с секцией Атрибуты:. Однострочный docstring — для очевидных хелперов.

Flow

Вход

• Пользователь назвал файл(ы) → работаем с ними.
• Иначе → git status --short (видит и изменённые M, и новые untracked ??).
• «обнови MODULE_INDEX.md» → полный glob всех кодовых файлов.

Шаг 1. Код (*.py / *.mq4 / *.mqh / *.ipynb)

Для каждого in-scope файла:

1. Header — проверить/обновить по шаблону (см. «Шаблон file header»).
2. Docstrings — проверить/дополнить по правилам (см. «Docstrings»).
3. docs/<category>/<module>.md — создать/обновить по mapping. В docs отразить: назначение, входы/выходы, запуск, ограничения.

Этот скилл не создаёт и не меняет поведенческий код — допускает только header/docstring-правки. Создание кода ведёт test-driven-development и правила AGENTS.md.

Шаг 2. MODULE_INDEX.md

Обновить записи для in-scope code-файлов. При «обнови MODULE_INDEX.md» — полный glob: **/*.py, **/*.mq4, **/*.mqh, **/*.ipynb; исключить .venv/, __pycache__/, .git/, docs/archive/.

Колонки: Модуль | Назначение | Вход → Выход | Docs | Статус.

• Статусы переносить из текущего MODULE_INDEX.md или ставить ⚠️; не придумывать.
• Header неполный → -, не блокировать.
• Валидация: Grep ^\| \[ в MODULE_INDEX.md, проверить отсутствие битых ссылок.

Правила качества

• Не дублировать подробные docstrings в .md; в .md — обзор и ссылки.
• Не трогать wiki/ — за него отвечает скилл my:wiki.
• Если во время синхронизации обнаружено изменение поведения Python-кода — тесты ведут правила AGENTS.md и скилл test-driven-development. Этот скилл обновляет документацию, не код.

Common mistakes

Ошибка	Исправление
docs не обновлены после изменения CLI	Обновить секцию Использование в header и в docs
новый модуль есть в коде, но нет в MODULE_INDEX.md	Добавить строку в соответствующий раздел
дублирование описаний между несколькими docs	Оставить одну source-of-truth страницу, в остальных ссылки
правка .mqh «как UTF-16LE» ломает кодировку	Проверить file перед правкой; фактическая кодировка UTF-8