From 137e160f1a948d3b7c5a32f6cd442976dc059aba Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 4 Sep 2026 16:41:53 +0000 Subject: [PATCH] docs: review document for #451 Issue: #451 User-Visible: no --- docs/reviews/SPEC-REVIEW-451-r2.md | 149 +++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-451-r2.md diff --git a/docs/reviews/SPEC-REVIEW-451-r2.md b/docs/reviews/SPEC-REVIEW-451-r2.md new file mode 100644 index 00000000..fe1f2d14 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-451-r2.md @@ -0,0 +1,149 @@ +# SPEC-REVIEW-451-r2 + +- **Issue:** https://github.com/Matysh/houseplan-card/issues/451 +- **Этап:** spec (PROCESS.md §2.4) +- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4 (зелёный вердикт бюджет + не тратит, #227) +- **Материал:** `docs/specs/451-render-performance.md`, коммит `2bf65d8bc894c223a3fd3098cac66d0af22fcfcb` + (`git rev-parse HEAD` на момент вывода), ветка `issue/451-render-performance` +- **Вердикт:** зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0 + +## Скоуп ревью r2 (по дельте, PROCESS.md §2.10) + +Предыдущий раунд — `docs/reviews/SPEC-REVIEW-451-r1.md`, вердикт жёлтый, High 0 / +Medium 3, материал зафиксирован на коммите `71c3360363991a042fbf3d84a6aeb4ecb772c83f` +(SHA резолвится и сейчас, это прямой предок текущего HEAD — `git merge-base +--is-ancestor 71c33603 HEAD` истинно, находка «мёртвый SHA» не применима). + +Дельта раунда — `git diff 71c33603..2bf65d8b -- docs/specs/451-render-performance.md`: +7 хунков, все внутри одного файла ТЗ, ни один не расширяет скоуп и не меняет +контракт поведения (Q1/Q2, AC1-AC12, §6-9 не тронуты). Автор сам объявил это +как «правки по SPEC-REVIEW r1» одним комментарием, перечислив M1/M2/M3 — дельта +подтверждена построчно и совпадает с заявленным без остатка. + +Разбор в r2 сокращён до дельты: заново проверены только участки текста, которые +правка задевает (M1/M2/M3 и их непосредственный контекст — §0 «Связано», §11.3, +AC13, §13.3, §14 п.7, §15). Продуктовая рамка (§1 сценарий, §2 что видит +человек, §7.1 обязательные разделы, AC1-AC12, §18 «принято предположительно») +не переоткрывалась — основание в разделе «Унаследовано из r1» ниже. + +## Как проверялось + +1. Прочитан текст всех трёх находок r1 и комментарий автора «Исправления по + SPEC-REVIEW r1» в issue #451. +2. Получен точный дифф правки: `git diff 71c3360363991a042fbf3d84a6aeb4ecb772c83f..2bf65d8bc894c223a3fd3098cac66d0af22fcfcb -- docs/specs/451-render-performance.md`. +3. Для каждой из M1/M2/M3 подтверждено построчно, что упомянутая проблемная + строка либо удалена, либо заменена корректной ссылкой (см. таблицу ниже). +4. Проверено отсутствие остаточных упоминаний удалённых сущностей во всём + файле: `grep -n "PERFORMANCE.md\|SCREENSHOTS.md\|5 538\|5538" + docs/specs/451-render-performance.md` — ноль совпадений вне уже + рассмотренных строк §11.3 (сами числа `3 432`/`98,9`/`4,2` присутствуют + намеренно, как новое обоснование). +5. Новое обоснование `hardMaxMs` в §11.3 сверено с телом issue #451: + `3 432 мс` — итоговая сумма из строки «Перетаскивание: суммарно в + обновлениях» таблицы A/B-эксперимента; `98,9 мс` — среднее обновление + сценария «Наведение мыши (5 с)» из исходной таблицы замеров. Оба числа + реальны и присутствуют в issue дословно (сверено `gh issue view 451 + --json body,comments`), в отличие от снятого `5 538 мс`, для которого r1 + не нашёл источника. +6. Арифметика новой фразы «500 мс на 120 moves… не более 4,2 мс на событие» + проверена: 500/120 = 4,1(6) — округление в сторону ceiling («не более 4,2») + математически корректно как верхняя граница, хоть и не самое плотное число; + это не искажает вывод и не является новой непрослеживаемой догадкой. +7. Проверено, что коммит `2bf65d8b` не тронул ничего, кроме + `docs/specs/451-render-performance.md` (`git show --stat 2bf65d8b`), и несёт + корректные трейлеры `Issue: #451` / `User-Visible: no` — правка ТЗ не + является видимым пользователю поведением, `no` уместен. +8. Дважды сверено, что дельта локальна и не подпадает ни под одно условие + «разбор остаётся полным» из §2.10: `dev` не ушёл вперёд (задача ветвится от + него же, ребейза не было), контракт поведения не менялся, новая подсистема + не затронута, объём дельты (12 строк добавлено/удалено в одном файле) на + порядки меньше исходного ТЗ (515 строк). + +Гейты (`typecheck`/`test`/`build`/смоки/perf) не прогонялись — на этапе `spec` +продуктового кода нет, диапазон изменений всей задачи по-прежнему только +`docs/specs/**` и `docs/reviews/**`. Это то же осознанное решение, что и в r1, +не пропуск. + +## Закрытие раунда r1 + +| Находка | Чем закрыта | Где это видно | +|---|---|---| +| **M1** — `docs/PERFORMANCE.md` назван обязательным артефактом, хотя не существует | Все три упоминания удалены, единственным каноном оставлен существующий `demo/performance/README.md` | `docs/specs/451-render-performance.md:13` (Связано), AC13 (строка 392), §14 п.7 (строка 455), §15 (строка 472) — `docs/PERFORMANCE.md` отсутствует во всём файле (`grep` ноль совпадений) | +| **M2** — `docs/SCREENSHOTS.md` в §13.3 не существует | Ссылка заменена реальным процессом: `PROCESS.md` §8, `demo/docs/capture.mjs`, `npm run docs:accept` | `docs/specs/451-render-performance.md:430-431` | +| **M3** — верхняя граница «5 538 мс» в §11.3 не подтверждена ни одним источником | Число снято; обоснование `hardMaxMs` теперь опирается только на дважды процитированные в issue числа — `3 432 мс` (pan, суммарно) и `98,9 мс` (hover, среднее), с явным выводом целевого значения 4,2 мс/событие | `docs/specs/451-render-performance.md:329-334`; оба числа найдены в issue #451 (`gh issue view --json body,comments`) | + +Все три находки закрыты правкой текста, а не заявлением автора — проверено +чтением итогового файла, не с чужих слов. + +## Унаследовано из r1 + +Без повторной проверки в r2 принято всё, чего дельта не касается — документ +`docs/reviews/SPEC-REVIEW-451-r1.md`, материал `71c3360363991a042fbf3d84a6aeb4ecb772c83f` +(SHA живой, подтверждён `git merge-base --is-ancestor` выше): + +- обязательные разделы §7.1 присутствуют и в правильном порядке (сценарий, + что видит человек, проблема, скоуп/не-скоуп, контракт, UX/touch/a11y, модель + данных, performance, AC1-AC13, план тестов, план реализации, release- + артефакты, риски, откат, §18); +- продуктовые решения владельца Q1 (deferred-last-wins после + `pointerup`/`pointercancel`) и Q2 (обычный hover в скоупе, лёгкий слой) + корректно перенесены в контракт §6.3/§8.3 и не переоткрываются как вопросы; +- диагноз причин A/B/C в §3 построчно сверен с `dev` в r1 и не является + догадкой (диагностика в `_renderBody`, `_view`/`_zoom` как `state: true`, + отсутствие `shouldUpdate`, единый источник трёх `data-*` атрибутов); +- non-scope (§5) очерчивает границу без расширения при реализации; +- AC1-AC13 пронумерованы, метод доказательства указан для каждого, проверяемы + структурными assertions §11.2, а не субъективными оценками; +- «один жест — один результат» симметричен для трёх редакторов через §8.4; +- откат (§17) содержит конкретный механизм, а не формальность; +- ссылки на связанные issue (#34, #82, #137, #156, #380, #396, #449) + существуют и релевантны. + +Дельта r2 ни одного из этих пунктов не задевает: правки лежат только в трёх +изолированных фрагментах (ссылки на несуществующие файлы и одно число), ни один +AC, продуктовое решение или обязательный раздел не переписаны. + +## Находки + +Нет. High: 0. Medium: 0. Новых догадок, выданных за факт, дельта не внесла — +оба новых числа (`3 432`, `98,9`) прослеживаются к issue дословно. + +## Что не проверялось и почему + +- **Продуктовый код** — по-прежнему не существует для #451; гейты `spec` этого + не требуют. +- **Полнота dependency-списка §6.2, реалистичность бюджетов §11.3 в рантайме, + полная матрица редакторских жестов** — те же три пункта, что и в r1, + делегированы на код-ревью (§18 ТЗ явно называет их «принято предположительно» + либо доказываемыми `unit`/`performance` на этапе реализации); дельта r2 их не + меняла и не должна была. +- **Арифметическая точность округления 4,1(6)→4,2** проверена вручную (см. п.6 + выше), отдельного гейта для этого нет и не требуется — это текстовое + обоснование, а не защитный AC. + +## Материал раунда + +- Ветка: `issue/451-render-performance` +- HEAD на момент вывода: `2bf65d8bc894c223a3fd3098cac66d0af22fcfcb` +- Предыдущий SHA (r1): `71c3360363991a042fbf3d84a6aeb4ecb772c83f` — живой, + прямой предок текущего HEAD +- Дерево материала: `docs/specs/451-render-performance.md` (единственный + изменённый в дельте файл) +- Команда поиска дельты: `git diff 71c3360363991a042fbf3d84a6aeb4ecb772c83f..2bf65d8bc894c223a3fd3098cac66d0af22fcfcb -- docs/specs/451-render-performance.md` + +--- + + + +## Материал раунда + +- Ветка: `issue/451-render-performance`, коммит `2bf65d8bc894` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `125aadd5cb53e6af3ffd14998c20855dbfd2d503` + ``` + git log --all --format='%H %T' | grep 125aadd5cb53 + ``` +- ТЗ `docs/specs/451-render-performance.md`, блоб `7c323a29110974aae369077214b9e2a74d9387c1` + ``` + git log --all --find-object=7c323a29110974aae369077214b9e2a74d9387c1 -- docs/specs/451-render-performance.md + ```