ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Переписать прозу пяти ТЗ ступени 1 по форме ТЗ ступени 2 #228

New Issue
Closed
opened 2026-09-06 12:56:42 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-06 12:56:42 +03:00
Owner
Copy link
Copy source

Part of #206

Цель

Пять ТЗ ступени 1 (docs/labs/events-enriched.md, top-pages-daily.md,
session-overview.md, dq-errors-daily.md, utm-effectiveness.md) написаны
27 августа Opus'ом одним коммитом, и владелец при чтении их забраковал
(2026-09-06): образы вместо утверждений («не заводит ни один боевой склад»,
«не поддаться соблазну разложить на диск»), заголовки-метафоры («Зерно и
форма», «Паспорт визита», «Торговый блок, массивами как в источнике»,
«Ловушка задания»), обороты, которые по-русски не говорят. Чинить по строчке
дороже, чем написать заново.

Результат тикета: те же пять ТЗ, с тем же содержанием, написанные заново
ясным русским языком по форме ТЗ ступени 2 docs/labs/superset-chart.md.

Урок в обмен на переписывание — читаемость: ТЗ, которое менти разбирает как
шараду, не учит ничему. Спека («Программа учебных лаб», ступень 1) говорит,
что ТЗ «выполняются как есть» и допускает их точечный пересмотр в
реализации. Этот тикет содержание не пересматривает: меняется только проза.

Решения, принятые здесь

Это вкусовая часть; исполнитель их не пересматривает.

Неприкосновенное (переносится дословно или с минимальной правкой формы):

  • имена объектов, источники, форма (представление или таблица), движок,
    ключ шардирования, ритм пересборки, наличие или отсутствие задачи в
    dm_transform и homework_check;
  • полный список колонок каждой витрины и формулы вычисляемых колонок;
  • все SQL-фрагменты и запросы самопроверки;
  • пункты «Приемка» чекбоксами: смысл каждого пункта сохраняется, формулировку
    можно упростить;
  • уроки заданий: «слой — это договор», доля из слагаемых, атрибуция по
    событию, витрина переживает источник, единственное исключение из правила
    _v. Урок остается, образ вокруг него уходит;
  • предупреждения о типичных ошибках (ARRAY JOIN теряет события с пустым
    массивом; среднее готовых долей врет; и другие по тексту). Содержание
    предупреждения сохраняется, подается прямо: что произойдет, как это
    заметить.

Форма — по образцу docs/labs/superset-chart.md: заголовок с названием
задания и объекта, «Чему учит» одной-двумя фразами без метафор, «Сначала
прочитать» ссылками на главы путеводителя, «Роль витрины» — зачем она
аналитику, «Что сделать» — форма, источник, колонки, ключи, ритм; «Как
проверить себя»; «Приемка». Названия разделов называют предмет, а не образ:
«Состав колонок», «Форма и источник», «Ключ шардирования», «Типичная ошибка».
Группы колонок внутри списка называются по-простому: «время и посетитель»,
«действие», «UTM-метки», «устройство и регион», «товары и покупка».

Язык. Обращение «вы» строчными. Без «ё», без «менти». Короткие фразы,
одна мысль на фразу. Ни одной фразы старой прозы не сохранять ради экономии:
если фраза выглядит нормально, ее можно оставить, но по умолчанию текст
пишется заново по содержанию, а не правится. Без олицетворений («витрина
отвечает», «таблица знает»), без калек. Термины — из CONTEXT.md и
путеводителя.

Без законов. Владелец (2026-09-06): это учебный материал, цель — хорошие
навыки, все остальное инструменты. Договоренности стенда («форма по зерну»,
«читать через _v», явный список колонок) подаются не как правила, а как
выбор с доводом: что этот навык дает и что ломается без него. Слова
«правило», «нельзя», «обязательно», «запрещено» заменять объяснением
последствия; где довод не складывается в одну фразу, оставить ссылку на
README лаб или справочник и не давить. Исключение — техническая
невозможность (например, ARRAY JOIN теряет строки): там прямое
предупреждение уместно.

Объем. Каждое ТЗ не длиннее нынешнего; ожидается короче. Таблицы колонок
уместны там, где сейчас списки в абзацах.

README лаб (владелец, 2026-09-06): раздел «Общие правила ступени 1»
переписывается в том же тоне, что и ТЗ: договоренности стенда как выбор с
доводом, ссылки из новых ТЗ ведут сюда. Заголовок раздела сменить на
«Как принято на ступени 1» или близкий: слово «правила» из заголовка уходит.
Раздел «Самопроверка» и таблица ступени 1 правятся только там, где повторяют
старые метафоры или слова «правило/нельзя/обязательно».

Кому поручать

Эксперимент проведен 2026-09-06: задание 1 events-enriched.md написали
gpt-5.6-sol и gpt-6-astra (Codex, medium) по одному брифу, владелец читал
вслепую. Победила Astra: «объясняет ощутимо получше, язык не такой
механический». Прозу всех пяти файлов пишет Codex на gpt-6-astra, medium,
одним тредом, по одному файлу на проход, чтобы форма сошлась; вариант
задания 1 из эксперимента берется за основу. Оговорка владельца: Astra
следует инструкциям буквально, поэтому бриф выверять строже, а в ревью
смотреть, не исполнила ли она лишнее из AGENTS.md и скиллов.
gpt-5.6-terra не запускать.

Astra в эксперименте спросила, правило ли стенда «изменение зерна требует
материализации». Ответ владельца (2026-09-06): это не жесткое правило, а
принятая на стенде договоренность о том, что полезнее. В новых ТЗ писать
«на стенде так принято» со ссылкой на «Общие правила ступени 1» в README
лаб, а не «по правилу задания» и не «обязательно». Ревью постановки — deep-reasoner. Ревью реализации —
две линии: craftsman свежей сессией на уместность и язык; вторая линия —
сверка фактуры со старыми файлами построчно (колонки, формулы, SQL, приемка)
— fast-worker или Codex, механически. Финальная вычитка — свежий тред Sol по
скиллу ai-text-lint плюс оптика литературного русского; фактура заморожена.

Критерии приемки

  • Пять файлов переписаны по форме superset-chart.md; набор разделов
    одинаковый у всех пяти, кроме разделов, у которых в старом ТЗ есть свой
    предмет (исключение из правила _v, атрибуция по событию).
  • Список колонок, формулы, SQL и смысл пунктов приемки совпадают со
    старыми файлами построчно; отчет сверки приложен к PR.
  • grep -n 'ё\|менти' docs/labs/*.md молчит; форм «ты/твой/тебе» нет.
  • В пяти ТЗ и в переписанном разделе README слова «правило», «нельзя»,
    «обязательно», «запрещено» встречаются только там, где речь о
    технической невозможности; каждое вхождение названо в PR.
  • Заголовков-образов нет: в grep -n '^##' docs/labs/*.md каждый
    заголовок называет предмет раздела.
  • Ссылки из пяти файлов ведут на существующие файлы и якоря (скрипт из
    #226).
  • Владелец прочитал хотя бы одно ТЗ целиком и не нашел фраз, которые
    «так не говорят».

Границы

  • Меняются пять файлов ТЗ ступени 1 и раздел «Общие правила ступени 1»
    в docs/labs/README.md (точечно — «Самопроверка» и таблица ступени 1).
    Справочник docs/architecture/dm.md не трогается: тон «форма по зерну»
    там — долг, записан в заметках карты #206. Спека, путеводитель, DDL, даг homework_check,
    ТЗ ступени 2 и дашборда не трогаются.
  • Содержание ТЗ не пересматривается: ни колонки, ни ключи, ни проверки.
    Найденная по ходу ошибка в фактуре — вопрос владельцу, не правка.
  • Стенд не трогать.

Сначала прочитать

  1. docs/labs/superset-chart.md — образец формы и языка.
  2. Пять старых ТЗ — как источник содержания.
  3. docs/handbook/storage-layers.md и docs/handbook/README.md — куда
    вести ссылки «Сначала прочитать».
  4. AGENTS.md, разделы «Цель репозитория» и «Язык».

Команды проверки

F="docs/labs/events-enriched.md docs/labs/top-pages-daily.md docs/labs/session-overview.md docs/labs/dq-errors-daily.md docs/labs/utm-effectiveness.md"
grep -n 'ё\|менти' $F docs/labs/README.md
grep -n -i 'правил\|нельзя\|обязател\|запрещ' $F docs/labs/README.md
python3 -c "import re,sys; [print(f,i+1,l.rstrip()) for f in sys.argv[1:] for i,l in enumerate(open(f)) if re.search(r'(?<![\wа-яё])(ты|тебе|тебя|твой|твоя|твое|твои|тобой)(?![\wа-яё])', l, re.I)]" $F
grep -n '^##' $F

Сверка фактуры: для каждой пары старый/новый файл — список имен в обратных
кавычках и все блоки sql должны совпадать как множества; разница
печатается и объясняется в PR.

Part of #206 ## Цель Пять ТЗ ступени 1 (`docs/labs/events-enriched.md`, `top-pages-daily.md`, `session-overview.md`, `dq-errors-daily.md`, `utm-effectiveness.md`) написаны 27 августа Opus'ом одним коммитом, и владелец при чтении их забраковал (2026-09-06): образы вместо утверждений («не заводит ни один боевой склад», «не поддаться соблазну разложить на диск»), заголовки-метафоры («Зерно и форма», «Паспорт визита», «Торговый блок, массивами как в источнике», «Ловушка задания»), обороты, которые по-русски не говорят. Чинить по строчке дороже, чем написать заново. Результат тикета: те же пять ТЗ, с тем же содержанием, написанные заново ясным русским языком по форме ТЗ ступени 2 `docs/labs/superset-chart.md`. Урок в обмен на переписывание — читаемость: ТЗ, которое менти разбирает как шараду, не учит ничему. Спека («Программа учебных лаб», ступень 1) говорит, что ТЗ «выполняются как есть» и допускает их точечный пересмотр в реализации. Этот тикет содержание не пересматривает: меняется только проза. ## Решения, принятые здесь Это вкусовая часть; исполнитель их не пересматривает. **Неприкосновенное** (переносится дословно или с минимальной правкой формы): - имена объектов, источники, форма (представление или таблица), движок, ключ шардирования, ритм пересборки, наличие или отсутствие задачи в `dm_transform` и `homework_check`; - полный список колонок каждой витрины и формулы вычисляемых колонок; - все SQL-фрагменты и запросы самопроверки; - пункты «Приемка» чекбоксами: смысл каждого пункта сохраняется, формулировку можно упростить; - уроки заданий: «слой — это договор», доля из слагаемых, атрибуция по событию, витрина переживает источник, единственное исключение из правила `_v`. Урок остается, образ вокруг него уходит; - предупреждения о типичных ошибках (`ARRAY JOIN` теряет события с пустым массивом; среднее готовых долей врет; и другие по тексту). Содержание предупреждения сохраняется, подается прямо: что произойдет, как это заметить. **Форма** — по образцу `docs/labs/superset-chart.md`: заголовок с названием задания и объекта, «Чему учит» одной-двумя фразами без метафор, «Сначала прочитать» ссылками на главы путеводителя, «Роль витрины» — зачем она аналитику, «Что сделать» — форма, источник, колонки, ключи, ритм; «Как проверить себя»; «Приемка». Названия разделов называют предмет, а не образ: «Состав колонок», «Форма и источник», «Ключ шардирования», «Типичная ошибка». Группы колонок внутри списка называются по-простому: «время и посетитель», «действие», «UTM-метки», «устройство и регион», «товары и покупка». **Язык.** Обращение «вы» строчными. Без «ё», без «менти». Короткие фразы, одна мысль на фразу. Ни одной фразы старой прозы не сохранять ради экономии: если фраза выглядит нормально, ее можно оставить, но по умолчанию текст пишется заново по содержанию, а не правится. Без олицетворений («витрина отвечает», «таблица знает»), без калек. Термины — из `CONTEXT.md` и путеводителя. **Без законов.** Владелец (2026-09-06): это учебный материал, цель — хорошие навыки, все остальное инструменты. Договоренности стенда («форма по зерну», «читать через `_v`», явный список колонок) подаются не как правила, а как выбор с доводом: что этот навык дает и что ломается без него. Слова «правило», «нельзя», «обязательно», «запрещено» заменять объяснением последствия; где довод не складывается в одну фразу, оставить ссылку на README лаб или справочник и не давить. Исключение — техническая невозможность (например, `ARRAY JOIN` теряет строки): там прямое предупреждение уместно. **Объем.** Каждое ТЗ не длиннее нынешнего; ожидается короче. Таблицы колонок уместны там, где сейчас списки в абзацах. **README лаб** (владелец, 2026-09-06): раздел «Общие правила ступени 1» переписывается в том же тоне, что и ТЗ: договоренности стенда как выбор с доводом, ссылки из новых ТЗ ведут сюда. Заголовок раздела сменить на «Как принято на ступени 1» или близкий: слово «правила» из заголовка уходит. Раздел «Самопроверка» и таблица ступени 1 правятся только там, где повторяют старые метафоры или слова «правило/нельзя/обязательно». ## Кому поручать Эксперимент проведен 2026-09-06: задание 1 `events-enriched.md` написали gpt-5.6-sol и gpt-6-astra (Codex, medium) по одному брифу, владелец читал вслепую. Победила Astra: «объясняет ощутимо получше, язык не такой механический». Прозу всех пяти файлов пишет Codex на gpt-6-astra, medium, одним тредом, по одному файлу на проход, чтобы форма сошлась; вариант задания 1 из эксперимента берется за основу. Оговорка владельца: Astra следует инструкциям буквально, поэтому бриф выверять строже, а в ревью смотреть, не исполнила ли она лишнее из AGENTS.md и скиллов. gpt-5.6-terra не запускать. Astra в эксперименте спросила, правило ли стенда «изменение зерна требует материализации». Ответ владельца (2026-09-06): это не жесткое правило, а принятая на стенде договоренность о том, что полезнее. В новых ТЗ писать «на стенде так принято» со ссылкой на «Общие правила ступени 1» в README лаб, а не «по правилу задания» и не «обязательно». Ревью постановки — deep-reasoner. Ревью реализации — две линии: craftsman свежей сессией на уместность и язык; вторая линия — сверка фактуры со старыми файлами построчно (колонки, формулы, SQL, приемка) — fast-worker или Codex, механически. Финальная вычитка — свежий тред Sol по скиллу ai-text-lint плюс оптика литературного русского; фактура заморожена. ## Критерии приемки - [ ] Пять файлов переписаны по форме `superset-chart.md`; набор разделов одинаковый у всех пяти, кроме разделов, у которых в старом ТЗ есть свой предмет (исключение из правила `_v`, атрибуция по событию). - [ ] Список колонок, формулы, SQL и смысл пунктов приемки совпадают со старыми файлами построчно; отчет сверки приложен к PR. - [ ] `grep -n 'ё\|менти' docs/labs/*.md` молчит; форм «ты/твой/тебе» нет. - [ ] В пяти ТЗ и в переписанном разделе README слова «правило», «нельзя», «обязательно», «запрещено» встречаются только там, где речь о технической невозможности; каждое вхождение названо в PR. - [ ] Заголовков-образов нет: в `grep -n '^##' docs/labs/*.md` каждый заголовок называет предмет раздела. - [ ] Ссылки из пяти файлов ведут на существующие файлы и якоря (скрипт из #226). - [ ] Владелец прочитал хотя бы одно ТЗ целиком и не нашел фраз, которые «так не говорят». ## Границы - Меняются пять файлов ТЗ ступени 1 и раздел «Общие правила ступени 1» в `docs/labs/README.md` (точечно — «Самопроверка» и таблица ступени 1). Справочник `docs/architecture/dm.md` не трогается: тон «форма по зерну» там — долг, записан в заметках карты #206. Спека, путеводитель, DDL, даг `homework_check`, ТЗ ступени 2 и дашборда не трогаются. - Содержание ТЗ не пересматривается: ни колонки, ни ключи, ни проверки. Найденная по ходу ошибка в фактуре — вопрос владельцу, не правка. - Стенд не трогать. ## Сначала прочитать 1. `docs/labs/superset-chart.md` — образец формы и языка. 2. Пять старых ТЗ — как источник содержания. 3. `docs/handbook/storage-layers.md` и `docs/handbook/README.md` — куда вести ссылки «Сначала прочитать». 4. `AGENTS.md`, разделы «Цель репозитория» и «Язык». ## Команды проверки ```bash F="docs/labs/events-enriched.md docs/labs/top-pages-daily.md docs/labs/session-overview.md docs/labs/dq-errors-daily.md docs/labs/utm-effectiveness.md" grep -n 'ё\|менти' $F docs/labs/README.md grep -n -i 'правил\|нельзя\|обязател\|запрещ' $F docs/labs/README.md python3 -c "import re,sys; [print(f,i+1,l.rstrip()) for f in sys.argv[1:] for i,l in enumerate(open(f)) if re.search(r'(?<![\wа-яё])(ты|тебе|тебя|твой|твоя|твое|твои|тобой)(?![\wа-яё])', l, re.I)]" $F grep -n '^##' $F ``` Сверка фактуры: для каждой пары старый/новый файл — список имен в обратных кавычках и все блоки ```sql``` должны совпадать как множества; разница печатается и объясняется в PR.
ddmitry added the wayfinder:task label 2026-09-06 12:56:42 +03:00
ddmitry self-assigned this 2026-09-06 14:54:16 +03:00
ddmitry commented 2026-09-06 15:45:30 +03:00
Author
Owner
Copy link
Copy source

Резолюция

Сделано в PR #229 (ветка 228-labs-prose), слияние закроет тикет.

Что остается:

  • Пять ТЗ ступени 1 написаны заново по форме superset-chart.md, содержание прежнее: колонки, формулы, самопроверка, приемка совпадают со старыми файлами (отчет сверки — в PR). Файлы короче старых на 7–18 %.
  • README лаб: раздел «Как принято на ступени 1» вместо «Общих правил», договоренности как выбор с доводом; ссылки из ТЗ ведут на якорь #как-принято-на-ступени-1. «Самопроверка» и таблица ступени 1 правлены точечно.
  • Слов-законов в пяти ТЗ нет; единственное «правило» — в нетронутом разделе «Уборка» README.
  • У задания 5 нет раздела «Типичная ошибка»: предупреждение о прямом трафике живет в своем разделе, дубль убран.
  • Ответ владельца про материализацию при новом зерне отражен так: «витрину с новым зерном на стенде хранят готовым агрегатом» со ссылкой на README лаб.

Как делалось: бриф — Fable, ревью брифа — Opus (15 находок, среди них две блокирующие: пропущен точечный объем README и главное предупреждение задания 2). Проза — Codex gpt-6-astra medium, один тред, по файлу на проход. Ревью — Opus (craftsman) свежей сессией, 22 находки и 8 при перепроверке, все закрыты; Sonnet — построчная фактура. Вычитка — свежий тред Sol по ai-text-lint. Astra по ходу задала верный вопрос: в задании 5 нет совпадения суммы visitors, ошибку брифа поправил.

Пункт приемки владельца — прочитать хотя бы одно ТЗ целиком — остается на слиянии.

Следующий шаг по карте: ТЗ ступени 3, тикет заводится при старте работы, как и прежде.

## Резолюция Сделано в PR #229 (ветка `228-labs-prose`), слияние закроет тикет. **Что остается:** - Пять ТЗ ступени 1 написаны заново по форме `superset-chart.md`, содержание прежнее: колонки, формулы, самопроверка, приемка совпадают со старыми файлами (отчет сверки — в PR). Файлы короче старых на 7–18 %. - README лаб: раздел «Как принято на ступени 1» вместо «Общих правил», договоренности как выбор с доводом; ссылки из ТЗ ведут на якорь `#как-принято-на-ступени-1`. «Самопроверка» и таблица ступени 1 правлены точечно. - Слов-законов в пяти ТЗ нет; единственное «правило» — в нетронутом разделе «Уборка» README. - У задания 5 нет раздела «Типичная ошибка»: предупреждение о прямом трафике живет в своем разделе, дубль убран. - Ответ владельца про материализацию при новом зерне отражен так: «витрину с новым зерном на стенде хранят готовым агрегатом» со ссылкой на README лаб. **Как делалось:** бриф — Fable, ревью брифа — Opus (15 находок, среди них две блокирующие: пропущен точечный объем README и главное предупреждение задания 2). Проза — Codex `gpt-6-astra` medium, один тред, по файлу на проход. Ревью — Opus (craftsman) свежей сессией, 22 находки и 8 при перепроверке, все закрыты; Sonnet — построчная фактура. Вычитка — свежий тред Sol по ai-text-lint. Astra по ходу задала верный вопрос: в задании 5 нет совпадения суммы `visitors`, ошибку брифа поправил. **Пункт приемки владельца** — прочитать хотя бы одно ТЗ целиком — остается на слиянии. **Следующий шаг по карте:** ТЗ ступени 3, тикет заводится при старте работы, как и прежде.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
No labels wayfinder:task
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees ddmitry
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#228