docs(generator): уточнена мат-спека по итогам ревью, handoff для передачи
- Зачем:
- повторное адверсариальное ревью нашло ошибку в формуле межсессионной
паузы (двойной счёт кулдауна) и незакрытый контракт публикации
device/geo; дизайн-этап завершён, работа передаётся исполнителю.
- Что:
- исправлена формула паузы (баланс цикла, минус длительность визита);
зафиксированы каденция device/geo «на каждое событие, как в сиде»,
правило выбора возвращающегося, стартовое распределение страниц,
калибровка по медиане и среднему, инвариант потолков конфигурации,
компактное хранение профиля ссылкой на сид-сессию.
- уточнены критерии приёмки (среднее паузы вместо медианы, счёт шага
«товары», имена полей времени) в обеих спеках.
- добавлен handoff .scratch/handoffs/2026-06-10-generator-spec-to-codex.md
(передача на детальный план/реализацию), отработавший handoff от
2026-06-09 удалён.
- Проверка:
- цифры спеки сверены замерами по полным data/*.jsonl (стартовые страницы
58/24/17, шаги воронки 98>=94>=56>=35>=25, device 1000 строк / 99
уникальных); повторное ревью свежим агентом блокеров не оставило.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Dmitry Dementiev
co-authored by
Claude Fable 5
Claude Fable 5
parent
0b5fc64f6f
commit
bcca8f5127
@@ -1,52 +0,0 @@
|
||||
# Handoff: переработка генератора (steady-stream, иерархическая модель)
|
||||
|
||||
Дата: 2026-06-09
|
||||
Ветка: `feature/data-generator`
|
||||
Жанр: одноразовые леса́ (ADR-0003) — durable-рассуждение в ADR/спеке, не здесь.
|
||||
|
||||
> Место: `.scratch/handoffs/` по [ADR-0003](../../docs/adr/0003-handoffs-in-scratch.md)
|
||||
> и `AGENTS.md` (перекрывают generic-дефолт скилла «temp dir» — у владельца
|
||||
> мультимашинность + worktrees, где `/tmp` не переживает).
|
||||
|
||||
## Где остановились
|
||||
|
||||
Брейнсторм-сессия (`brainstorm-with-docs`) завершена **на этапе документов** —
|
||||
кода НЕ трогали. Зафиксировано направление переработки генератора и расчищена
|
||||
рамка под реализацию. Дальше — отдельная follow-up-спека по математике, затем
|
||||
реализация.
|
||||
|
||||
## Контекст и решения (ссылки, не пересказ)
|
||||
|
||||
- **Решение «почему» (генератор A, не реплей C):**
|
||||
[`docs/adr/0004-steady-stream-synthetic-generator.md`](../../docs/adr/0004-steady-stream-synthetic-generator.md)
|
||||
- **Форма доработки «что строим» (требования, без математики), статус Draft:**
|
||||
[`docs/specs/2026-06-09-generator-rework-hierarchical.md`](../../docs/specs/2026-06-09-generator-rework-hierarchical.md)
|
||||
— там же раздел **Open questions** (список вопросов для мат-спеки) и
|
||||
**Validation** (критерии приёмки). Не дублирую сюда.
|
||||
- **Глоссарий:** `CONTEXT.md` — добавлены «популяция пользователей» /
|
||||
«возвращающийся пользователь».
|
||||
- **Диагноз дефекта текущей реализации:** `generator/KNOWN_ISSUES.md`.
|
||||
|
||||
## Следующий шаг
|
||||
|
||||
**Написать follow-up-спеку по математике** генеративной модели. Перечень вопросов
|
||||
— в разделе *Open questions* спеки доработки (распределения, session-timeout,
|
||||
раскладка иерархии по тикам, персистентность популяции, `event_type` diversity).
|
||||
|
||||
## Ловушки (одной строкой; детали — в спеке)
|
||||
|
||||
- Воронка живёт в **`page_url_path`**, не в `event_type` (в сиде 100% `pageview`).
|
||||
- device/geo — **сессионный** контекст уровня `click`, не «свойство пользователя».
|
||||
- Модель интенсивности (`_calculate_events_count`, `_hour_factor`) — **сохраняем**;
|
||||
переписываем только модель сущностей (`generate_batch`). Текущую реализацию
|
||||
инкрементально не чиним.
|
||||
|
||||
## Suggested skills (для следующей сессии)
|
||||
|
||||
- **`conventional-commits`** — закоммитить готовые доки (см. git ниже).
|
||||
- **`brainstorm-with-docs`** (или `grill-with-docs`) — для follow-up-спеки по
|
||||
математике: продолжает тот же стиль (durable-доки + правка CONTEXT/ADR inline).
|
||||
- **`tdd`** — на этапе реализации rewrite (у генератора уже есть pytest-набор
|
||||
`generator/tests/`).
|
||||
- **`adversarial-review`** / **`code-review`** — ревью переписанной модели
|
||||
сущностей перед вливанием ветки.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Handoff: спеки генератора готовы — передача на детальный план и реализацию
|
||||
|
||||
Дата: 2026-06-10
|
||||
Ветка: `feature/data-generator`
|
||||
Жанр: одноразовые леса́ (ADR-0003) — durable-рассуждение в спеках/ADR/CONTEXT, не здесь.
|
||||
|
||||
> Место: `.scratch/handoffs/` по [ADR-0003](../../docs/adr/0003-handoffs-in-scratch.md)
|
||||
> (перекрывает generic-дефолт скилла «temp dir»: мультимашинность + worktrees).
|
||||
> Предыдущий handoff (2026-06-09-generator-rework.md) отработал и удалён.
|
||||
|
||||
## Где остановились
|
||||
|
||||
Дизайн-этап переработки генератора **завершён**. Спека математической модели
|
||||
написана, прошла **два** адверсариальных ревью свежими агентами (второе ревью
|
||||
ловило ошибки правок первого — практика себя оправдала), все находки закрыты,
|
||||
ключевые цифры перепроверены замерами по полному сиду. Кода по-прежнему
|
||||
не трогали.
|
||||
|
||||
Разделение ролей (см. память проекта): дизайн/спеки — Fable, **детальный план
|
||||
и реализация — Codex 5.5**. Следующая сессия — скорее всего, подготовка задачи
|
||||
для Кодекса или сама реализация.
|
||||
|
||||
## Документы (источники истины, не пересказываю)
|
||||
|
||||
- **Мат-модель (главный документ для исполнителя):**
|
||||
`docs/specs/2026-06-10-generator-math-model.md` — марковская цепочка по
|
||||
страницам, формула «популяция ↔ интенсивность ↔ пауза», кулдаун, правило
|
||||
30 минут на рестарт, критерии приёмки.
|
||||
- **Форма доработки:** `docs/specs/2026-06-09-generator-rework-hierarchical.md`
|
||||
(Open questions закрыты ссылкой на мат-спеку).
|
||||
- **Почему генератор, а не реплей:** `docs/adr/0004-steady-stream-synthetic-generator.md`.
|
||||
- **Профиль сид-датасета (опора калибровки):** `CONTEXT.md`, раздел
|
||||
«Профиль сид-датасета» — измерено по полным файлам 2026-06-10.
|
||||
- **Диагноз дефекта старого кода:** `generator/KNOWN_ISSUES.md`.
|
||||
|
||||
## Ловушки (одной строкой; детали — в спеках)
|
||||
|
||||
- Ранний «факт» **«1..7 событий на визит» был неверен** (срез файла); реально
|
||||
1..27, медиана 10. Если встретишь «1..7» где-то ещё в доках/коде — это
|
||||
остатки ошибки, чинить по профилю сида.
|
||||
- **Формула паузы в мат-спеке обязательна** при смене λ/популяции; кулдаун в
|
||||
неё не прибавляется (уже учтён балансом). Вторая ревизия исправляла именно
|
||||
двойной счёт — не откатить случайно.
|
||||
- **device/geo публикуются на каждое событие** (как в сиде) — это контракт с
|
||||
ETL, не деталь.
|
||||
- `event_timestamp` событий — **запланированное** время, не момент отправки
|
||||
тика (иначе метки прилипают к сетке тиков).
|
||||
- Модель интенсивности (`_calculate_events_count`) сохраняем; дефолт
|
||||
`GEN_LAMBDA_BASE_PER_MIN` меняется 200 → 30.
|
||||
|
||||
## Следующий шаг
|
||||
|
||||
Передать пару спек Кодексу: детальный план реализации → код. Уровень спек
|
||||
сознательно «решения и инварианты, без алгоритмов» — конкретику исполнитель
|
||||
достраивает сам. Возможная подготовка: оформить задачу в `.scratch/<feature>/`
|
||||
по `docs/agents/issue-tracker.md` (скилл `to-issues`, если план дробить).
|
||||
|
||||
## Suggested skills (для следующей сессии)
|
||||
|
||||
- **`to-issues`** — если решим дробить реализацию на задачи в локальном трекере.
|
||||
- **`tdd`** — для этапа реализации (pytest-набор `generator/tests/` существует,
|
||||
но писался под старую модель — пересмотр под новую неизбежен).
|
||||
- **`adversarial-review`** / **`code-review`** — ревью реализации против
|
||||
мат-спеки перед вливанием.
|
||||
- **`conventional-commits`** — коммиты по правилам репозитория.
|
||||
Reference in New Issue
Block a user