docs(handoff): контекст для уточнения документации по архитектуре
- Зачем:
- следующая сессия чинит профильные доки, отставшие от кода; нужен
быстрый вход с готовым рабочим списком, а отработанный handoff про
корневой README больше не актуален.
- Что:
- добавлен handoff 2026-06-06-docs-accuracy-fixes.md со ссылкой на
аудит, порядком починки и ключевым контекстом.
- удалён отработанный 2026-06-06-root-readme-polish.md.
- Проверка:
- открыть .scratch/handoffs/2026-06-06-docs-accuracy-fixes.md и
.scratch/docs-accuracy-audit/findings.md.
This commit is contained in:
@@ -0,0 +1,56 @@
|
||||
# Handoff: уточнение документации по архитектуре
|
||||
|
||||
Дата: 2026-06-06 · Язык сессии: русский
|
||||
|
||||
Следующая сессия чинит профильную документацию, которая отстала от кода. Рабочий список
|
||||
уже собран и сверён с кодом — **не переоткрывай его заново**, бери готовый:
|
||||
[`.scratch/docs-accuracy-audit/findings.md`](../docs-accuracy-audit/findings.md)
|
||||
(12 находок, разнесены по серьёзности, с привязкой файл:строка).
|
||||
|
||||
## Что делать
|
||||
|
||||
Чинить доки по списку аудита, **начиная с 🔴**:
|
||||
- `ARCHITECTURE.md` — три концептуальных искажения: схема `ods.*_errors`, DQ-split подан
|
||||
как взаимоисключающий (а строка попадает в обе таблицы), сборка `dds.event`
|
||||
(browser-driven LEFT JOIN, не симметричный JOIN; «сироты» из location отбрасываются).
|
||||
- `SUPERSET_DASHBOARD.md` — `make superset-export` задокументирован как рабочий, но
|
||||
`export_dashboard.py` падает на устаревших импортах. **Решение за владельцем:** чинить
|
||||
импорты или убрать команду из доки, если экспорт больше не нужен.
|
||||
- `REPO_MAP.md` — пропущен первый шаг ETL `sql/ods/20_stg_to_ods.sql` и ряд артефактов.
|
||||
|
||||
Потом 🟡 (неполнота параметров и DQ-маркеров) и 🟢 (мелочи).
|
||||
|
||||
## Контекст, который сэкономит время
|
||||
|
||||
- **Источник истины — код**, не доки: `sql/ddl/*`, `sql/ods|dds|dm/*`, `airflow/dags/*`,
|
||||
`superset/*.py`, `docker-compose.yml`, `Makefile`. Аудит уже сослался на нужные строки.
|
||||
- **Ключевой инсайт:** концептуальные темы ARCHITECTURE (DQ-split, сборка DDS с сиротами)
|
||||
точнее и подробнее разобраны в **уроках 2–3 курса** (`docs/course/lessons/`). Де-факто
|
||||
каноном стали уроки, а не ARCHITECTURE. Скорее всего проще подтянуть ARCHITECTURE к
|
||||
формулировкам уроков, чем переписывать с нуля — и заодно проверить, что урок и код
|
||||
совпадают (уроки свежие, но тоже стоит сверить).
|
||||
- **Codex сейчас стоит** — параллельной записи в ветку нет, можно править ARCHITECTURE
|
||||
спокойно. Но привычку держать аддитивно не теряй: `git add` только своих файлов.
|
||||
- **Стиль/голос доков:** чистый литературный русский без лишних англицизмов (см. память
|
||||
`plain-literary-russian`); house style осознанный (тире «—», «ё», жирное начало абзаца,
|
||||
двоеточие перед списком) — линтером не правим. `ai-text-lint` гонять только на настоящие
|
||||
маркеры, context `article`.
|
||||
- **Проверять claim на коде, а не на глаз** — этот подход в этой сессии и вскрыл все
|
||||
расхождения.
|
||||
|
||||
## Состояние
|
||||
|
||||
- **Ветка** `docs/advanced-clickstream-course`. Эта сессия добавила два коммита:
|
||||
`ce7f03b` (корневой README переписан под менти+песочницу) и `5bd215d` (аудит в .scratch).
|
||||
Корневой README трогать больше не нужно — он самостоятельно корректен (только ссылается
|
||||
на доки).
|
||||
- **Рабочее дерево чистое** (после коммита/пуша этой сессии).
|
||||
- 🅿️ **Future, не в скоупе:** лицензия стенда (роадмап = CC BY 4.0; для кода обычно MIT —
|
||||
кандидат на dual MIT + CC BY); фейк-бейдж лицензии в README уже убран.
|
||||
|
||||
## Suggested skills
|
||||
|
||||
- `grill-with-docs` — выверить формулировки ARCHITECTURE против доменной модели и кода,
|
||||
обновляя док по ходу решений (ровно под эту задачу).
|
||||
- `ai-text-lint` — прогон правок (context `article`, house style не снимать).
|
||||
- `conventional-commits` — для коммитов.
|
||||
Reference in New Issue
Block a user