progcode/editorial/reviews/2025-07-draft.md

# P89 — июль 2025: метрики продукта для инженера

## Область draft-пакета

Пакет заменяет только три overlay-статьи:

- <code>editorial-2025-07-practice-product-metrics</code> — «Метрики продукта для инженера: построить цепочку, а не поднять conversion».
- <code>editorial-2025-07-mechanism-product-metrics</code> — «Почему рост метрики не является решением: denominator, cohort и guardrail».
- <code>editorial-2025-07-field-product-metrics</code> — «Полевой журнал продуктовой метрики: evidence до решения».

Единственный исполняемый артефакт — <code>web/scripts/upgrade-2025-07.mjs</code>. Все events, cohorts, subjects, requestId, периоды, ratios, решения и результаты — fixed synthetic in-memory JS literals. Скрипт не читает и не пишет files, Git, network, CI, clock, telemetry, production или user data и не выполняет side effect. Пакет не подключает overlay к registry, не меняет README, очередь, <code>articles.json</code>, app-страницы, docs, staging, commit или push.

## Исследование и историческая граница

Проверка источников выполнена 31.07.2026 обычными HTTPS-запросами без авторизации и TLS bypass. Историческая граница — 31 июля 2025: OpenTelemetry закреплён immutable commit, работы Microsoft Research опубликованы в 2017 и 2019 годах.

| Источник | Закрепление | Узко подтверждаемое утверждение | Граница |
| --- | --- | --- | --- |
| [OpenTelemetry events](https://raw.githubusercontent.com/open-telemetry/semantic-conventions/c01aa89d9a13042e56536c60975139c50e764796/docs/general/events.md) | tag <code>v1.31.0</code>, commit <code>c01aa89d9a13042e56536c60975139c50e764796</code>, 11.03.2025 | event имеет уникальное имя; convention документирует его структуру и attributes; dynamic values не включаются в event name. | Не определяет продуктовую causal effect, denominator, guardrail или ship criterion. |
| [Safe Velocity with Controlled Rollouts](https://www.microsoft.com/en-us/research/uploads/prod/2020/06/Safe-Velocity-ICSE-SEI.pdf) | ICSE-SEIP 2019, author version | local feature, success и guardrail metrics имеют разные роли; guardrail не должен деградировать при rollout. | Описывает controlled rollouts Microsoft, не доказывает эффект произвольной local metric в другом продукте. |
| [A Dirty Dozen Metric Interpretation Pitfalls](https://www.microsoft.com/en-us/research/uploads/prod/2020/08/2017-08-KDDMetricInterpretationPitfalls.pdf) | KDD 2017, author version | другой состав наблюдений и telemetry loss могут исказить metric delta; numerator и denominator полезно разбирать отдельно. | Не заменяет дизайн конкретного эксперимента, power analysis, privacy policy или pipeline validation. |

Причинная цепочка, названия полей, synthetic input и правило HOLD — собственная инженерная конструкция статей. Они не приписаны источникам как framework guarantee.

## Проход 1 — факты, техника и источники

- <code>createFixedProductMetricInput</code> выдаёт только один из четырёх frozen fixed cases. <code>inspectFixedProductMetric</code> считает unique subjects для opened, confirmed и render_failed; не принимает произвольный input как доказательство.
- Успешный case требует attribution, declared denominator и единственный cohort-period. <code>prepareFixedProductDecision</code> после PASS создаёт только <code>needs-human-owner-decision</code>; production effect остаётся <code>not-attempted</code>.
- Negative paths проверены отдельно: нет attribution → <code>missing-attribution-rule</code>; другой период → <code>mixed-cohort-or-period</code>; <code>all-events</code> вместо unique opened subjects → <code>wrong-denominator</code>.
- Из источников в тексте взяты только документированная форма события, разные роли local/success/guardrail и риск неверного состава наблюдений. Нет утверждения, что рост confirm сам доказывает причинность или что конкретный threshold применим вне synthetic example.

**Вердикт прохода 1:** пройдено. Код и текст разделяют зафиксированный учебный contract, human decision и реальные продуктовые выводы.

## Проход 2 — голос, плотность, ситуация и цена

| Статья | Первые два абзаца | Основной текст | Артефакт | Проверяемый финал |
| --- | --- | ---: | --- | --- |
| practice | Изолированный рост conversion и цена false release/повторного расследования | 6 648 | causal funnel, event contract, fixture | test на confirm без requestId возвращает HOLD |
| mechanism | Разный состав numerator/denominator и цена false positive | 6 410 | matrix, ratio contract, negative cases | событие из другого period останавливает расчёт |
| field | Число отделено от context и цена неповторимого decision | 6 291 | decision record, evidence loop, stop example | другой инженер восстанавливает contract по карточке |

Три текста соответствуют голосу М8: автор не продаёт «рост метрик», а сравнивает риск, owner и воспроизводимый путь. Термины раскрыты в момент первого использования: cohort, attribution, denominator, guardrail, local metric и decision record. Формула «симптом → причина → проверка → действие» сохраняется в каждом разделе. Синтетические числа не выдаются за telemetry, реальные деньги, людей или инциденты.

**Вердикт прохода 2:** пройдено. Усиленный <code>audit:draft</code> подтвердил проблему и цену ошибки в первых двух абзацах, диапазон 5–15 тыс. знаков, таблицу, figure, code example, ordered sequence и источники.

## Проход 3 — SVG, fixture и выпуск

Последовательность фактически выполненных проверок:

- <code>node --check web/scripts/upgrade-2025-07.mjs</code> — PASS.
- <code>node web/scripts/upgrade-2025-07.mjs --verify-fixture</code> — PASS, **11/11** assertions.
- <code>cd web &amp;&amp; npm run audit:draft -- scripts/upgrade-2025-07.mjs</code> — PASS: **6 648 / 6 410 / 6 291** body chars после независимой редакторской правки.
- <code>xmllint --noout</code> для трёх SVG — PASS; safety scan чист: нет <code>script</code>, <code>foreignObject</code>, <code>javascript:</code>, <code>data:image</code> и event-handler attributes.
- Sharp renders на 375 px просмотрены вручную. Funnel сохраняет отдельную красную ветку guardrail; matrix читается в четыре строки; evidence loop показывает HOLD ветку и не обрезает подписи.

| Asset | Смысл | Результат 375 px |
| --- | --- | --- |
| <code>product-metrics-2025-causal-funnel.svg</code> | change → opened → confirmed → human review и guardrail | PASS: стрелки, подписи шагов и красный guardrail видимы. |
| <code>product-metrics-2025-metric-guardrail-matrix.svg</code> | четыре измерительных условия и HOLD | PASS: контраст и строки читаемы, нижняя оговорка не обрезана. |
| <code>product-metrics-2025-decision-evidence-loop.svg</code> | evidence loop с веткой repair contract | PASS: пять шагов и HOLD branch различимы на узком экране. |

Full build и <code>audit:articles</code> намеренно не запускались: overlay не подключён к registry. Их должен выполнить независимый интегратор после подключения. Commit и публикация не выполнялись.

**Вердикт прохода 3:** draft-пакет готов к независимой приёмке, но не опубликован.

## Выпуск после независимой приёмки

### 1. Факты и техника

Редактор проверил источники заново. Immutable OpenTelemetry commit `c01aa89d9a13042e56536c60975139c50e764796` от 11 марта 2025 подтверждает уникальное имя события, документированную структуру и низкую кардинальность имени. PDF Safe Velocity (ICSE-SEIP 2019) подтверждает разные роли data-quality, guardrail, success и local metrics; PDF Dirty Dozen (KDD 2017) подтверждает, что sample/telemetry mismatch может сделать delta недостоверной и требует разбирать numerator и denominator. Эти факты не используются как доказательство causal effect или ship decision для synthetic набора.

Заново выполнены `node --check`, fixture 11/11 и усиленный draft audit. Все три code examples выполнены вручную: valid case заканчивается `needs-human-owner-decision`, wrong denominator и mixed period — `stop-before-product-decision` с точной причиной. Скрипт сохраняет границу: фиксированные literals в памяти, без запроса dashboard, telemetry или production action.

### 2. Редактура и голос

Полное чтение выявило чрезмерный общий вводный блок у mechanism и field. Он удалён и заменён на два специальных раздела: проверку ratio до интерпретации и чтение карточки решения. Поэтому статьи не пересказывают practice, а раскрывают собственный вопрос: доказательство измерения и воспроизводимое decision record. После правки основной текст составляет 6 648, 6 410 и 6 291 знак; в первых двух абзацах каждой названы проблема и цена ошибки. Термины раскрыты в контексте, а причинность оставлена проверяемой гипотезой, не обещанием фреймворка.

### 3. Визуал и выпуск

Три SVG прошли XML и safety scan. Независимый Sharp render на 375 px подтвердил, что causal funnel, metric matrix и evidence loop читаются без обрезания; у каждой figure есть содержательный alt и подпись. После подключения overlay целевой audit подтвердил: practice — одна figure, две таблицы и один example; mechanism и field — по одной figure, таблице и примеру. Registry содержит 259 уникальных ревизий, `git diff --check` чист, production build успешно сгенерировал 374 страницы.