workflow-ai 1.0.63 → 1.0.65

package/src/skills/review-result/workflows/review.md

@@ -0,0 +1,209 @@
+# Воркфлоу: Review — Проверка результата выполнения задачи
+
+Основной воркфлоу скила. Применяется для всех типов тикетов.
+
+## Алгоритм выполнения
+
+### 0. Быстрый выход (short-circuit)
+
+1. Прочитай тикет из `review/{TICKET-ID}.md`
+2. Найди секцию `## Ревью`
+3. Если секция существует — посмотри **последнюю запись** таблицы:
+   - `passed` или `⏭ skipped` → немедленно верни `status: passed`, **остановись**
+   - `failed` → перейди к шагу 1 (механическая предпроверка)
+4. Если секции нет → перейди к шагу 1
+
+### 1. Механическая предпроверка (verify-artifacts)
+
+**Автоматическая проверка (основной путь):**
+
+Запусти скрипт верификации артефактов:
+
+```bash
+node .workflow/src/skills/review-result/scripts/verify-artifacts.js <ticket-id|ticket-path>
+```
+
+Где аргумент — либо ticket_id (`IMPL-006`), либо путь к файлу тикета (`.workflow/tickets/review/IMPL-006.md`).
+
+Прочитай key-value пары из блока `---RESULT---`. Скрипт возвращает:
+- `status` — `passed` (все проверки ok) или `failed` (есть критические проблемы)
+- `dod_completion_pct` — процент выполнения DoD (0–100)
+- `dod_total` / `dod_completed` — абсолютные счётчики DoD-чекбоксов
+- `result_filled` — заполнена ли секция Summary в Result (`true` / `false`)
+- `missing_files` — comma-separated список файлов из «Изменённые файлы», которых физически нет
+- `fail_reasons` — (только при failed) перечисление критериев, которые привели к отказу
+
+**Быстрый отказ по результатам скрипта:**
+
+| Условие | Действие |
+|---------|----------|
+| `status: failed` | → итоговый вердикт `failed`, не запускать содержательное AI-ревью |
+| `result_filled == false` | → `failed`: секция Result пуста |
+| `dod_completion_pct == 0` | → `failed`: ни один пункт DoD не отмечен. **Это жёсткое правило:** запрещено интерпретировать таблицу `PASS`/`FAIL` в тексте Result как замену `- [x]` в DoD. Source of truth — только чекбоксы `- [x]`. Если исполнитель не проставил их — это его ошибка, повод для `failed`, а не для AI-рационализации. |
+| `missing_files` не пуст | Зафиксировать как issue, продолжить AI-ревью |
+
+Если скрипт показал критические проблемы — переходи сразу к шагу 5 (формирование вердикта `failed`) и запиши в issues поле `fail_reasons` из вывода скрипта.
+
+**Ручная проверка (fallback):**
+
+Если скрипт недоступен или вернул ошибку — переходи к шагу 2 без предпроверки. Шаг 4.6 (верификация реальных изменений) покроет эти проверки вручную.
+
+### 2. Парсинг тикета
+
+Извлеки из тикета:
+
+| Поле | Где искать | Обязательно |
+|------|-----------|-------------|
+| **DoD** | Секция «Критерии готовности (Definition of Done)» — чеклист `- [ ]` / `- [x]` | Да |
+| **Детали задачи** | Секция «Детали задачи» — требования к реализации | Да |
+| **Результат** | Секция «Результат выполнения» — что сделано, изменённые файлы | Да |
+| **Тип задачи** | Frontmatter `type` | Да |
+| **executor_type** | Frontmatter `executor_type` (если есть) | Нет |
+
+### 3. Проверка каждого пункта DoD
+
+Для каждого критерия из DoD определи тип проверки и выполни:
+
+| Тип проверки | Описание | Как проверить |
+|--------------|----------|---------------|
+| `file_exists` | Файл существует по указанному пути | Read/Glob по пути. **Если не найден → fallback:** `Bash("ls -la {путь}")` (Glob не видит untracked dirs) |
+| `compilation` | Код компилируется / линтер проходит | Запуск lint/build |
+| `tests` | Тесты проходят | Запуск тестов |
+| `text` | Текстовый критерий выполнен | Поиск контента в файле |
+| `structure` | Структура соответствует шаблону | Сравнение с эталоном |
+
+> **Загрузи** `knowledge/dod-patterns.md` для определения типичных паттернов DoD по типу тикета.
+
+### 4. Сверка Result с требованиями
+
+Сравни секцию «Результат выполнения» с «Деталями задачи»:
+- Все ли требования учтены
+- Соответствует ли реализация описанию
+- Нет ли расхождений между заявленным и реальным
+
+### 4.5. Проверка с позиции целевой аудитории
+
+> **Применяется** когда результат — документ/ТЗ/спецификация для конкретного исполнителя.
+
+Если в DoD есть критерий типа *«файл самодостаточен»* или *«исполнитель не должен смотреть другие документы»*:
+
+| Проверка | Как проверить | Провал → |
+|----------|---------------|----------|
+| Credentials указаны или описано где взять | Искать плейсхолдеры `XXX`, `TODO`, `заменить на реальный` | failed |
+| Все системные зависимости перечислены | Для каждого API/библиотеки — проверить наличие в dependencies | failed |
+| Параметры вычислимы | Для условных параметров — описан способ получения значения | failed |
+| Environment-переключение описано | Если есть debug/dev/prod — описан механизм переключения | failed |
+
+**Правило:** прочитай документ глазами целевого исполнителя. Если он не может начать работу без дополнительных вопросов — `failed`.
+
+### 4.6. Верификация реальных изменений
+
+> **Применяется только** для тикетов с `executor_type != human`.
+
+> **Загрузи** `algorithms/verification.md` для формализованного алгоритма верификации.
+
+| Проверка | Как проверить | Провал → |
+|----------|---------------|----------|
+| Файлы-артефакты существуют | Проверить все файлы из «Изменённые файлы» через Read/Glob. **Если не найден → fallback:** `Bash("ls -la {путь}")` (Glob не видит файлы в новых untracked директориях). Только если оба способа не нашли → failed | failed |
+| Файлы содержат реальный контент | Открыть файл, убедиться что не шаблон/placeholder | failed |
+| Секция Result не пуста | Summary заполнен содержательно (не заглушка) | failed |
+| DoD соответствует реальности | Для каждого `[x]` — открыть артефакт и подтвердить | failed |
+
+### 4.7. Визуальная верификация скриншотов
+
+> **Применяется** при выполнении **любого** из двух условий:
+> - **(A)** В тикете (DoD, результаты TC, секция evidence, «Изменённые файлы») есть ссылки на `.png` файлы.
+> - **(B)** Тикет содержит TC или DoD с **визуальными критериями** — формулировки, описывающие как элемент выглядит пользователю: «оформлен как», «выглядит», «читаем», «контрастен», «виден», «выровнен», «не обрезан», «стилизован», «нет overflow», «визуально выделен», а также любые отрицания о внешнем виде («не голый», «не пустой», «без X»). Если хотя бы один TC содержит такую формулировку — шаг 4.7 обязателен.
+
+**Шаг 4.7.0 (при триггере B, без явных PNG-ссылок в тикете):**
+
+Прежде чем проверять скриншоты, определи, **существуют ли они вообще**. Исполнитель мог сохранить скрины, но не сослаться на них в тикете; либо мог не сделать скрины вовсе.
+
+1. Найди скриншоты: `Glob` по типичным местам хранения артефактов проекта (директория отчётов, директории снимков тестов) на `.png` файлы, фильтруя по ID тикета или имени теста.
+2. Если скриншоты найдены — перейди к основной проверке (шаги 1-3 ниже) для каждого найденного файла, сопоставимого с визуальным TC.
+3. Если скриншоты **не найдены**, а визуальные TC есть — это **finding**: evidence визуальных TC является только текстовым (DOM-assertions), без визуального артефакта. Зафиксируй как issue: «TC N.N содержит визуальный критерий "{формулировка}", но evidence — только DOM-assertion без скриншота. Визуальное свойство не может быть подтверждено программной проверкой существования DOM-узла».
+
+**Основная проверка (для каждого скриншота):**
+
+| Шаг | Действие | Провал → |
+|-----|----------|----------|
+| 1 | Открой файл через Read (Claude мультимодален — изображения читаются визуально) | failed (файл не существует) |
+| 2 | Прочитай заявление TC, к которому привязан скриншот (что именно должно быть видно) | — |
+| 3 | Визуально проверь: подтверждает ли скриншот заявленное? **Опиши своими словами**, что видишь на скриншоте, прежде чем выносить вердикт. Запрещено выносить вердикт без описания содержимого. | failed (скриншот не подтверждает заявленное) |
+
+**Вердикты по скриншоту:**
+- **MATCH** — скриншот однозначно подтверждает заявление TC. В записи ревью указать: «VV: {что видно} → MATCH»
+- **PARTIAL** — скриншот релевантен, но элемент обрезан, нечитаем или не доказывает утверждение однозначно
+- **MISMATCH** — скриншот не соответствует заявленному (другое содержимое, пустой, не тот экран)
+
+**Правила:**
+- MISMATCH любого скриншота → `failed` с указанием: какой файл, что заявлено, что видно на самом деле
+- PARTIAL — не блокирует, но фиксируется в issues как замечание
+- Issue из шага 4.7.0 (визуальный TC без скриншота) → не является автоматическим `failed`, но **фиксируется как issue уровня HIGH** и включается в самари ревью. Ревьюер не может подтвердить визуальный критерий без визуального evidence
+
+### 5. Формирование вердикта
+
+> **ВАЖНО:** Допустимы ТОЛЬКО два статуса: `passed` или `failed`.
+
+#### 5.1. Специальное правило для QA-тикетов
+
+> **Перед вынесением вердикта** проверь тип тикета (`type` в frontmatter). Если тип — `qa` (тестирование), применяй следующую логику:
+>
+> Обнаружение дефекта продукта (отсутствующий функционал, баг, BLOCKER) — это **правильно выполненная работа тестировщика**, а не провал тикета. Тестировщик не может починить продукт — его задача найти и задокументировать проблему.
+>
+> **PASS ревью QA-тикета** если тестировщик:
+> - Протестировал все сценарии (или обосновал почему сценарий невозможен)
+> - Задокументировал результат каждого сценария (PASS/FAIL/BLOCKER)
+> - Для найденных дефектов указал: описание, шаги воспроизведения, ожидаемый/фактический результат
+> - Приложил evidence (a11y tree assertion + описание шагов). **Скриншоты ОБЯЗАТЕЛЬНЫ, если указаны в DoD OR в разделе Result (раздел «Файлы-артефакты»/«Скриншоты»)**
+> - Если скриншоты приложены — они существуют физически и соответствуют заявленному (проверено шагом 4.7)
+> - **⛔ HIGH issues об отсутствующих файлах-артефактах БЛОКИРУЕТ passed**: если в ревью найдено, что заявленный скриншот/файл отсутствует физически — это `failed`, независимо от наличия a11y assertions
+>
+> **FAIL ревью QA-тикета** если:
+> - Не протестировал сценарий без объяснения
+> - Не задокументировал результат
+> - Не приложил evidence (ни a11y assertion, ни описания шагов)
+> - Заявил скриншоты в Result/DoD, но они физически не существуют (HIGH issue из шага 4.7.0)
+> - Приложил скриншоты, которые не соответствуют заявленному (MISMATCH по шагу 4.7)
+> - Пропустил дефект (не заметил явную проблему)
+
+#### 5.2. Стандартное правило
+
+Если **все** пункты DoD выполнены:
+
+```
+---RESULT---
+status: passed
+issues: []
+---RESULT---
+```
+
+Если **хотя бы один** пункт не выполнен:
+
+```
+---RESULT---
+status: failed
+issues:
+  - "Пункт DoD X не выполнен: ожидалось Y, получено Z"
+---RESULT---
+```
+
+### 6. Детализация замечаний (при failed)
+
+Для каждого невыполненного пункта:
+- Что ожидалось
+- Что получено
+- Файл/строка (если применимо)
+
+### 7. Пометка тикета
+
+1. Найди секцию `## Ревью` в тикете (если нет — создай с заголовком таблицы)
+2. Добавь новую запись **В КОНЕЦ таблицы**:
+
+```markdown
+| {дата} | {✅ passed / ❌ failed} | {краткое самари} |
+```
+
+3. Сохрани тикет в той же директории (`review/`)
+
+> **Порядок записей:** хронологический сверху вниз. Последняя строка = последнее ревью.