Analyst Doc

---
name: analyst-doc
description: Сборка документа для аналитика или тестировщика по закрытой задаче - описание изменений глазами пользователя плюс порядок функционального тестирования. Источник - spec.md задачи и история ветки; результат - analyst-doc.md в каталоге спеки и, если в проекте так принято, PDF на печать. Запускать, когда работа по задаче сделана и её надо передать на проверку. Триггер-фразы - «сделай документ для аналитика», «описание изменений и порядок тестирования», «документ на тестирование prj-42». Не использовать для технической документации и для описания API - это документ для того, кто в код не смотрит.
---

# Настройка под проект

> **Заполняется при инициализации шаблона** (см. [`docs/project-init.md`](../../../docs/project-init.md)).
> Пока таблица не заполнена - скилл на первом запуске спрашивает недостающее и предлагает записать сюда, а `close-task` про документ не спрашивает вовсе.

| Параметр | Значение |
| --- | --- |
| Источник содержания | `specs/<prefix>-<N>/spec.md`, у закрытой задачи - `specs/done/<prefix>-<N>/spec.md` |
| Дополняющий источник | `git log <ветка разработки>..HEAD` - то, что делалось по ходу и в спеку попасть не успело |
| Ветка разработки | `<пример: develop>` |
| Где живёт документ | `specs/<prefix>-<N>/analyst-doc.md` - едет в `specs/done/` вместе со спекой |
| Печатная оболочка | [`template.html`](template.html) в каталоге скилла |
| Сборка PDF | `<нужна / не нужна - шаг пропускается>` |
| Браузер для печати | `<macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome; Windows: /c/Program Files/Google/Chrome/Application/chrome.exe; «нет» - PDF не собирается>` |
| Куда кладём PDF | `<по умолчанию рабочий стол; в репозиторий не коммитим>` |
| Язык | русский |

# Назначение

Аналитик или тестировщик получает задачу на функциональное тестирование и не смотрит в код. Ему нужны два ответа: что изменилось с точки зрения пользователя и что именно проверять. Скилл собирает такой документ из спеки, не пересказывая спеку.

Спека написана для разработчика и ревьюера: там имена модулей, тексты запросов, контракты. Документ для аналитика - другой жанр, а не выжимка. Прямой пересказ спеки даёт бесполезный текст.

# Когда запускать

- Работа по задаче закончена, спека закрыта или близка к закрытию.
- Из скилла [`close-task`](../close-task/SKILL.md), шаг 5: при закрытии задачи он спрашивает, нужен ли документ. Нужен не всегда - на мелком багфиксе владелец отвечает «нет».
- Задачу передают на функциональное тестирование.
- Не запускать для технических описаний, документации API и инструкций разработчику - жанр другой.

# Формат: почему Markdown

Источник истины - `analyst-doc.md` в каталоге задачи, рядом со `spec.md` и `plan.md`. Причины:

- документ архивируется вместе со спекой обычным `git mv` каталога в `specs/done/` и не остаётся в чужой ветке;
- правится содержание, а не вёрстка: после вопроса аналитика владелец открывает MD и меняет формулировку;
- читается в дифе, в трекере и в редакторе без сборки.

HTML и PDF - производные. HTML собирается из MD в скретчпад и живёт до конца сессии, PDF отдаётся аналитику. В репозиторий не едет ни тот, ни другой: оба пересобираются из MD за секунду.

# Принципы

- **Читатель знает предметную область и интерфейс, но не код.** Ни одного имени модуля, процедуры, реквизита метаданных, ни одного фрагмента запроса, ни одного префикса `prj_`.
- **Объекты называются так, как их видит пользователь:** «форма „Банковские выписки“», «документ „Поступление на расчётный счёт“», «справочник „Предопределенные значения“».
- **Каждое удаление объясняется.** Если колонка или механизм убраны, надо сказать, почему они были мертвы. Иначе аналитик прочтёт это как потерю функциональности и заведёт дефект.
- **Раздел «что не менялось» обязателен.** Он задаёт границы проверки: без него аналитик либо проверяет лишнее, либо не проверяет нужное.
- **Известные ограничения пишутся прямо**, особенно те, что выглядят как дефект. Не написали - получите баг-репорт на ожидаемое поведение.
- **Документ не врёт про объём проверки.** То, что нельзя проверить за один заход (APDEX, обновление ИБ, поведение под нагрузкой), выносится отдельно с указанием срока.

# Алгоритм

## Шаг 1. Собрать материал

1. Ключ задачи: из аргумента, иначе из `git branch --show-current`.
2. Прочитать `spec.md`: разделы «Контекст и проблема», «Область изменений», «Поведение», «Критерии приёмки», «Вне области».
3. Прочитать `git log <ветка разработки>..HEAD` - по ходу работы почти всегда всплывает то, чего в исходной спеке не было. В документ это попасть должно.
4. Если в задаче были находки «не наше, но починили попутно» - они идут в документ наравне с плановыми изменениями: аналитик не знает, что было в плане.

## Шаг 2. Написать содержание

Шесть разделов, в этом порядке. Пустой раздел лучше выкинуть, чем оставить с формальной отпиской.

| № | Раздел | Что внутри |
| --- | --- | --- |
| 1 | Зачем это делалось | Проблема на языке пользователя и бизнеса, 2-3 абзаца. Не «рефакторинг запроса», а что именно работало не так |
| 2 | Что изменилось для пользователя | Ядро документа. Таблицей по объектам: что удалено и почему было мертво, что осталось прежним, что исправлено |
| 3 | Что осталось нетронутым | Списком. Границы проверки |
| 4 | Порядок тестирования | Таблица: № / что сделать / ожидаемый результат / отметка. Плюс врезка про то, под кем проверять |
| 5 | На что обратить внимание | Побочные эффекты, известные ограничения, что проверяется отложенно |
| 6 | Если что-то пойдёт не так | Наиболее вероятные сценарии отказа и что приложить к сообщению |

Шапка документа - заголовок первого уровня (суть изменения на языке пользователя, не имя задачи) и строка с задачей, разработчиком, датой и перечнем объектов.

**Шаги тестирования.** Формулировка - действие («Открыть журнал → …», «Взять 5 документов и сверить …»), а не «проверить, что…». У каждого шага ожидаемый результат, по которому видно, пройден он или нет. Порядок - от простого к сложному: открылось → состав → значения → отборы → сортировки → команды → проведение → обновление базы.

Колонка «Отметка» пустая - она под галочку того, кто проверяет. Остаётся в документе всегда, не только в PDF.

Критерии приёмки из спеки - сырьё, а не готовые шаги. Их надо переписать в действия и выкинуть те, что проверяются не руками (диагностика, отсутствие вхождений в коде, чистота `git status`).

**Разметка, которую читает печатная оболочка.** Четыре соглашения, остальное - обычный Markdown:

| В Markdown | Во что превращается при сборке PDF |
| --- | --- |
| Ячейка начинается с `**Удалено.**` | `<span class="gone">` - красным |
| Ячейка начинается с `**Без изменений.**` или `**Исправлено.**` | `<span class="kept">` - зелёным |
| Цитата `> **Под кем проверять.** …` | `<blockquote class="note">` - врезка серой полосой |
| Таблица порядка тестирования | `<table class="steps">` - узкая колонка `№`, колонка «Отметка» под галочку |

## Шаг 3. Сохранить документ

Записать `analyst-doc.md` в каталог задачи: `specs/<prefix>-<N>/analyst-doc.md`, у закрытой задачи - `specs/done/<prefix>-<N>/`. Если скилл вызван из `close-task`, документ коммитится до переноса спеки в архив, чтобы уехать в `specs/done/` вместе с ней.

## Шаг 4. Собрать PDF

Пропустить, если в настройке сборка PDF не нужна или браузер не указан.

1. Прочитать [`template.html`](template.html) - это печатная оболочка: стили A4 и слоты под содержание. Вёрстка рассчитана на печать, менять её без нужды не надо.
2. Преобразовать `analyst-doc.md` в HTML-фрагмент: заголовки, таблицы, списки, цитаты - один к одному, плюс соглашения из шага 2. Подставить фрагмент в слот `{{CONTENT}}`, заполнить `{{TITLE}}` и `{{FOOTER}}`, результат записать в скретчпад.
3. Собрать PDF через headless-браузер:

   ```bash
   # macOS
   CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
   "$CHROME" --headless=new --disable-gpu --no-pdf-header-footer \
     --print-to-pdf="$OUT_PDF" "file://$SRC_HTML"

   # Windows, git-bash
   CHROME="/c/Program Files/Google/Chrome/Application/chrome.exe"
   # запасной вариант: "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
   "$CHROME" --headless=new --disable-gpu --no-pdf-header-footer \
     --print-to-pdf="$(cygpath -w "$OUT_PDF")" "$(cygpath -w "$SRC_HTML")"
   ```

   В stderr браузер сыпет предупреждениями про USB и GPU - это шум, признак успеха только строка `NNNNN bytes written to file`.

4. Проверить, что PDF не пустой и сколько в нём страниц:

   ```bash
   perl -0777 -ne 'my @c = /\/Count\s+(\d+)/g; print "страниц: @c\n"' "$OUT_PDF"
   ```

   Ноль страниц или отсутствие `/Count` - вёрстка не отработала, разбираться, а не отдавать файл.

5. Положить PDF туда, куда сказал владелец; по умолчанию - на рабочий стол. Имя файла человеческое: `<prefix>-<N> Описание изменений и порядок тестирования.pdf`. В репозиторий PDF не коммитим.

## Шаг 5. Отдать

Сообщить путь к `analyst-doc.md`, путь к PDF и число страниц, перечислить разделы. Отдельно назвать решения, принятые при изложении, - что решено объяснять подробнее, что сознательно опущено как техническая деталь. Владелец знает контекст лучше и поправит.

Правка по вопросу аналитика делается в `analyst-doc.md`, PDF после неё пересобирается шагом 4. Пересборка с нуля из спеки принимает решения о подаче заново и даёт другой текст - так не делать.

# Типичные ошибки

| Ошибка | Чем плоха |
| --- | --- |
| Пересказ спеки своими словами | Получается документ ни для кого: аналитику лишнее, разработчику недостаточно |
| «Удалена колонка X» без объяснения | Читается как потеря функциональности, приводит к ложному дефекту |
| Шаг «проверить корректность работы формы» | Непроверяемо, проверяющий не знает, что считать успехом |
| Умолчание про известную медлительность или сброс настроек | Возвращается баг-репортом на ожидаемое поведение |
| Имена модулей и префиксы в тексте | Читатель не знает, что это, и не может проверить |
| Обещание, что всё проверяется за один заход | APDEX и обновление ИБ так не проверяются, документ теряет доверие |
| Правка PDF в обход Markdown | Следующая пересборка её затрёт |

# Замечания

- Скилл ничего не пушит сам. Коммит делает по ходу `close-task`; при самостоятельном запуске - спросить владельца.
- Если спека закрыта и лежит в `specs/done/`, документ всё равно собирается из неё - переоткрывать задачу не нужно.
- Если по задаче спеки нет вовсе (мелкий багфикс), собрать документ из истории ветки и явно сказать владельцу, что источником была только она; класть рядом со спекой в этом случае некуда - спросить, куда положить.

# Usage examples

| Command | What it does |
|---|---|
| `/analyst-doc` | Документ по задаче текущей ветки |
| `/analyst-doc prj-42` | Документ по задаче `prj-42` |