--- name: che-direct-analytics-skill description: "Собирает и рассчитывает данные Директа и Метрики раздельно, сверяет периоды, KPI и аномалии. Применяется для диагностики кампаний, ключей, CPA/ROAS/CTR и атрибуции; не распределяет неизвестную выручку по расходам." license: MIT metadata: version: 3.0.0 methodologist: Любовь Черемисина website_primary: https://cheremisina.ru website_secondary: https://cheremisina.online repository: https://github.com/LuCheremisina/marketing-skills display_name: CHE_direct-analytics-skill author: Любовь Черемисина --- # CHE_direct-analytics-skill — che-direct-analytics-skill ## Границы и принцип работы Навык только читает API и локальный SQLite-кэш. Он никогда не меняет кампании, ставки, бюджеты или цели. Любое предложенное действие — черновик для проверки аналитиком. Директ и Метрика — параллельные источники. `CrossSourceROAS` рассчитывается только по явно сопоставленным строкам: выручка Метрики ÷ расход Директа. Подписывай оба источника, период и правило сопоставления; это межисточниковая оценка. Неатрибутированная выручка остаётся отдельной строкой и никогда не распределяется по расходу. ## Настройка проекта Проверь `~/.direct_analytics/{project}/config.json`. Для нового проекта: ```bash python scripts/setup.py --new ``` Помимо OAuth-токенов, зафиксируй data contract: - `REPORT_TIMEZONE` — IANA timezone отчёта; - `UTM_SOURCE` и `UTM_MEDIUM` — фильтр трафика Директа, обычно `yandex` и `cpc`; - `UTM_CAMPAIGN_MAPPING` — `campaign_id` или `campaign_name`; - `ATTRIBUTION_MODE` — только `parallel` в первой версии; - `GUARDRAILS` — проектные цели и `min_abs_delta` для алертов; - `MONITOR_METRICS` и `COHORT_RULES` — список контролируемых KPI и regex-правила внутренних когорт. Не добавляй универсальные пороги CPA/ROAS: они должны быть заданы в конкретном проекте и иметь бизнес-смысл. ## Сбор фактов ```bash python scripts/collect.py --project NAME --date_from 2026-08-01 --date_to 2026-08-07 python scripts/collect.py --project NAME --scope keyword --scope ad --date_from D --date_to D ``` - По умолчанию собирается `core`: `campaign`, `device`, `region`, `placement`, `adnetwork`. - `keyword` и `ad` собираются только отдельными Direct Reports и только по явному `--scope`. - Все данные сохраняются по завершённым дням. Пустой день — валидный факт; ошибка API — `complete=false` и будет повторно запрошена при следующем запуске. - `--refresh` инвалидирует и пересобирает весь выбранный диапазон. - Collector печатает contract, покрытие дат, свежесть и ошибки. Успешный выход не является доказательством production-эффекта — только успешного чтения API. ## Аналитика и reconciliation ```bash python scripts/analyze.py --project NAME --period 7d --dim campaign --compare prev_period --format json python scripts/analyze.py --project NAME --dim keyword --date_from D --date_to D python scripts/analyze.py --project NAME --dim campaign --anomaly ``` Доступные разрезы: `campaign`, `device`, `region`, `keyword`, `placement`, `ad`, `day`, `adnetwork`. `campaign` и `day` читают reconciliation; поэтому могут показать Direct KPI, Метрика KPI и подписанные cross-source показатели. Остальные разрезы показывают только нативные Direct KPI, пока для них не настроено совместимое зерно Метрики. Если нужный scope отсутствует, `analyze.py` подскажет точную команду сбора. `--anomaly` применяет только `GUARDRAILS` проекта. Он не содержит скрытых глобальных правил и не рекомендует автоматическое отключение площадок. ## Диагностика и feedback ```bash python scripts/diagnose.py --project NAME --metric MetrikaRevenue \ --date_from 2026-08-01 --date_to 2026-08-07 --compare prev_period --format json python scripts/diagnose.py feedback --project NAME --run-id RUN_ID \ --verdict confirmed --actual-cause "Campaign was paused" \ --action-outcome "No change was applied" ``` `diagnose.py` возвращает `diagnosis_record`: - data-status, coverage, timezone и правила атрибуции; - trigger и сравниваемые периоды; - воронку `показы → клики → визиты/цели → транзакции/выручка`; - `confirmed_causes` только с прямым системным доказательством; - `likely_drivers` как численный вклад, не как причинное утверждение; - `hypotheses` и следующий read-only тест; - draft-действие с явным требованием approval для любого изменения кабинета. Human feedback хранит `confirmed`, `partial` или `refuted`, фактическую причину и результат действия. Он предназначен для измерения калибровки, не для неявного обучения модели. ## Monitor, бенчмарки и dashboards ```bash python scripts/monitor.py --project NAME --date 2026-08-10 --format json python scripts/benchmark.py --project NAME --period 30d --format html python scripts/dashboard.py --project NAME --spec report-spec.json --format html ``` Monitor использует четыре предыдущих сопоставимых дня недели за 28 дней, median и MAD. High alert требует одновременно статистической аномалии, проектной материальности и полного data-quality gate. При недостаточной истории возвращается `baseline_insufficient`. Доставка ограничена CLI + JSON/HTML: n8n, Telegram и scheduler не входят в навык. `benchmark.py` строит только внутренние когорты и показывает `n`, p25, median, p75. Внешний market benchmark не создаётся. LLM может превратить естественный запрос в `ReportSpec`, но `dashboard.py` принимает лишь JSON со списком зарегистрированных `metrics`, `dimension`, `period` либо `date_from/date_to` и `chart` из `table|line|bar`. Ответ всегда содержит исходный query-spec и data-status. Пример: ```json { "dimension": "campaign", "metrics": ["Cost", "MetrikaRevenue", "CrossSourceROAS"], "period": "30d", "chart": "bar", "top": 10 } ``` ## Quality gate Перед результатом применить `evals/shared.csv`, `evals/skill-specific.csv` и `evals/judge_prompt.md`. Арифметику, зерно данных, coverage, filters, reconciliation, нулевые знаменатели и baseline проверяет код; LLM оценивает только трассируемость и интерпретацию. Не вычислять общий балл. Запуск локального test gate: ```bash PYTHONPYCACHEPREFIX=/tmp/directanalytics-pycache \ python3 -m unittest discover -s tests -v ``` ### Shadow-mode до запуска мониторинга Для десяти исторических отклонений аналитик сохраняет `confirmed`, `partial` или `refuted` через `diagnose.py feedback`. В каждом `run_id` обязательны complete data-status и evidence trail. Локальный gate не обучает модель и не запускает мониторинг: ```bash python scripts/shadow_gate.py --project NAME --minimum-cases 10 --format json ``` Он считает долю подтверждённых диагнозов, false-certainty для явных `confirmed_cause`, precision high-priority кейсов (если они промаркированы) и медианное время до human verdict. Пока gate не `passed`, реальный запуск монитора запрещён процессом; CLI сам не создаёт расписание или доставку. ## Навигация по ресурсам - [references/api_notes.md](references/api_notes.md) — читать при соответствующем этапе workflow. ## Зависимости Python-зависимости: [requirements.txt](requirements.txt). Использовать разрешённое изолированное окружение; при отсутствии зависимостей раскрыть ограничение. ## Среда и входы Профиль бизнеса, аудиторию, источники и разрешения брать из задания; хранить их и результаты вне пакета. Методолог навыка не становится автором материала автоматически. Использовать только объявленные инструменты. Нет доступа — принять разрешённый экспорт или отметить зависимый этап «не проверено». Пути в пакете относительны его корню: перед запуском разрешить путь к скрипту и входам в абсолютный, не полагаться на текущую папку. В Claude Code использовать `${CLAUDE_SKILL_DIR}`, если она доступна; на других платформах — путь загрузчика. Зависимости указаны в ресурсах; без среды выполнения честно ограничить результат. Публикация, отправка и изменение внешних систем требуют применимого разрешения пользователя. ## Авторство Методолог навыка — **Любовь Черемисина**. Лицензия оригинальной методологии и кода этого пакета — MIT. - [Основной сайт](https://cheremisina.ru) - [Экспертные материалы](https://cheremisina.online) - [Навыки для маркетологов](https://github.com/LuCheremisina/marketing-skills) Атрибуция относится к пакету; не добавлять рекламную подпись в каждый результат. ## Ресурсы по необходимости - [evals/judge_prompt.md](evals/judge_prompt.md) — читать при проверке результата.