--- name: phase-review description: > Adaptive post-implementation phase verification through fresh subagents with S/M/L sizing (bug-fix → feature → architecture). Multi-agent pipeline with strict role zoning: Spec + Architecture (параллель) → Quality + Security + Forward-Look (параллель) → Adversarial Skeptic → fix → Regression Sweep → final report. Auto-scales 2 → 7 агентов в зависимости от размера фазы, чтобы не жечь токены на тривиальных правках. USE WHEN: an implementation phase is done and needs validation before moving to the next phase. Trigger phrases (RU/EN): «ревью фазы», «проверь фазу», «валидация фазы», «проверь что написал», «фаза готова», «phase review», «review phase», «verify phase», «validate phase». NOT for: PR/diff review (use differential-review), generic code review (use code-review-skill). Includes built-in security audit, architecture invariants check, forward-look stress test, adversarial paranoia filter, and post-fix regression sweep — отдельный security-review запускать не нужно. Integrates as Шаг 7 (Review) внутри Bulletproof. Specifically for: post-phase verification in multi-phase implementation plans (MASTER-PLAN.md, bulletproof workflow, SPARC phases). Based on Superpowers methodology (obra/superpowers) + multi-agent zoning + adaptive sizing. --- # Phase Review — Адаптивная многоэтапная верификация через свежих субагентов ## Почему именно так (не менять без причины) Один агент с историей сессии психологически некритичен к своему коду. Свежий субагент видит код так же, как его увидит следующий разработчик — без предположений «что я имел в виду». **Правило 1 — fresh subagents:** все Reviewer'ы — это всегда свежие субагенты. Текущая сессия играет только роль оркестратора + исполнителя фиксов на Шаге 3. **Правило 2 — зонирование агентов:** разные роли = разные агенты, чтобы глубина анализа была максимальной. Ни один агент не делает двух ролей сразу. **Правило 3 — adaptive sizing:** S/M/L по размеру фазы. Bug-fix не должен прогонять полный 7-агентный pipeline — это перерасход. Архитектурное изменение должно — иначе пропустим инвариант. Размер определяется автоматически на Шаге 0.5; пользователь может override. **Порядок (полный, для L-размера):** 1. Шаг 0 — Context preparation (текущая сессия) 2. Шаг 0.5 — Size detection (S/M/L) 3. Шаг 1 — Declarations Gate (параллель: 1A Spec + 1B Architecture) 4. Шаг 2 — Risk Profiles (параллель: 2A Quality + 2B Security + 2C Forward-Look) 5. Шаг 2.5 — Adversarial Skeptic (sequential) 6. Шаг 3 — Fix application (текущая сессия, только REAL findings) 7. Шаг 3.5 — Regression Sweep (sequential, fresh взгляд на diff фиксов) 8. Шаг 4 — Итоговый отчёт **Какие шаги пропускаются на S/M — см. Шаг 0.5 ниже.** --- ## Шаг 0 — Подготовка контекста (текущая сессия, всегда) ``` Перед запуском ревью собери контекст: 1. ТЗ ФАЗЫ Прочитай исходное ТЗ (CLAUDE.md, MASTER-PLAN.md или указанный файл). Выведи одной строкой: что должна была сделать фаза. 2. ИЗМЕНЁННЫЕ ФАЙЛЫ git diff --name-only HEAD~1 (или указанный диапазон). git diff --shortstat — для оценки объёма. 3. КОМАНДА ТЕСТОВ Если есть — зафиксируй. 4. PROJECT CONTEXT - Приоритет фазы: ЗАПУСТИТЬ / ПРОДАТЬ / МАСШТАБИРОВАТЬ - Объём в первый месяц: десятки / сотни / тысячи - Стадия продукта: pre-MVP / MVP / production / scale - Чувствительные участки в diff: auth, PII, платежи, ЭЦП, файл-аплоад, raw SQL, внешние API, фоновые задачи 5. ФАЙЛ АРХИТЕКТУРНЫХ ИНВАРИАНТОВ architecture/.../правила-нерушимые.md, ADR/, INVARIANTS.md. Зафиксируй путь или отметь «нет». 6. ASSUMPTION LOG (заимствовано из Superpowers) Запиши ключевые допущения, которые делал при реализации фазы: «я предполагал, что X», «я считал, что Y не нужно». Они передаются Skeptic'у для проверки. ``` --- ## Шаг 0.5 — Size Detection (текущая сессия, новый) Определяет S / M / L. От размера зависит, какие агенты запускаются и сколько токенов потратится. ### Авто-детекция ``` S — SMALL (bug-fix, копипаста, правка текста): условие: < 4 файлов И < 100 строк diff И нет sensitive-участков триггер-слова: «фикс», «баг», «опечатка», «правка», «hotfix» стоимость: 2-3 агента (~25-30% от L) M — MEDIUM (фича, новый эндпоинт, рефакторинг): условие: 4-15 файлов ИЛИ есть sensitive-участки ИЛИ новый компонент/слой/таблица триггер-слова: «фича», «новый функционал», «эндпоинт», «компонент» стоимость: 4-6 агентов (~60-70% от L) L — LARGE (архитектура, миграция, новый домен): условие: > 15 файлов ИЛИ затронуты ≥3 модуля/слоя ИЛИ миграция БД ИЛИ новый bounded context триггер-слова: «архитектура», «миграция», «новый домен», «переписывание», «refactor across» стоимость: 7 агентов (100%, при > 15 файлов — батчинг по 5-8) ``` ### Override Пользователь может задать явно: - `/phase-review --size S` (или `M` / `L`) - В тексте задачи: «прогони S-ревью», «полное L-ревью» ### Sensitive-bump Если в diff затронуты sensitive-участки (auth/PII/платежи/ЭЦП/файл-аплоад/ raw SQL без ORM), **минимальный размер = M**. S автоматически апгрейдится до M, чтобы security и forward-look не пропустить. ### Матрица: какой агент на каком размере | Шаг | Роль | Агент | S | M | L | |-----|---------------------|--------------------|---|---|---| | 1A | Spec Compliance | `reviewer` | ✓ | ✓ | ✓ | | 1B | Architecture Invar. | `system-architect` | — | ✓¹| ✓ | | 2A | Code Quality | `code-analyzer` | ✓ | ✓ | ✓ | | 2B | Security | `security-auditor` | ✓²| ✓ | ✓ | | 2C | Forward Look | `perf-analyzer` | — | ✓ | ✓ | | 2.5 | Adversarial Skeptic | `analyst` | — | ✓³| ✓ | | 3 | Fix application | session | ✓ | ✓ | ✓ | | 3.5 | Regression Sweep | `reviewer` (fresh) | ✓⁴| ✓⁵| ✓ | | 4 | Final report | session | ✓ | ✓ | ✓ | ¹ — только если файл инвариантов существует, иначе ARCH_SKIP без агента. ² — на S запускается только при sensitive-bump (см. выше). Иначе пропуск. ³ — на M пропускается, если суммарно < 5 находок (нечего фильтровать). ⁴ — на S запускается только если применено ≥ 3 фиксов или хотя бы один security-фикс. ⁵ — на M запускается, если применён хотя бы один фикс. **Если ничего не поправили — Шаг 3.5 пропускается на любом размере.** --- ## Шаг 1 — DECLARATIONS GATE Запусти **одним сообщением** субагентов согласно матрице. На S — только 1A; на M/L — 1A + 1B параллельно. ### 1A — SPEC COMPLIANCE (агент `reviewer`) ``` Ты — скептичный Spec Reviewer. Проверяешь, что реализация соответствует ТЗ. Не доверяешь отчётам исполнителя — читаешь реальный код. КОНТЕКСТ ФАЗЫ: [текст ТЗ] ИЗМЕНЁННЫЕ ФАЙЛЫ: [список] ASSUMPTION LOG ИСПОЛНИТЕЛЯ: [допущения из Шага 0.6] Прочитай каждый файл. Проверь: 1. ПОКРЫТИЕ ТЗ — что не реализовано или реализовано частично? 2. OVER-BUILDING — что реализовано, чего в ТЗ не было? 3. ПРОТИВОРЕЧИЯ — где реализация делает не то, что в ТЗ? 4. ASSUMPTION CHECK — допущения исполнителя соответствуют ТЗ или противоречат ему? Формат: [ФАЙЛ: путь, строка] Тип: [НЕ РЕАЛИЗОВАНО / ЛИШНЕЕ / ПРОТИВОРЕЧИЕ / ОШИБОЧНОЕ ДОПУЩЕНИЕ] Критичность: [БЛОКЕР / СРЕДНЕ / МЕЛКО] Статус: SPEC_PASS / SPEC_WARN / SPEC_FAIL ``` ### 1B — ARCHITECTURE INVARIANTS (агент `system-architect`, M/L only) ``` Ты — Architecture Invariants Reviewer. Сверяешь только с инвариантами. Это НЕ code review. ФАЙЛ ИНВАРИАНТОВ: [путь] ИЗМЕНЁННЫЕ ФАЙЛЫ: [список] Извлеки правила (A-01, A-02, …). Для каждого изменённого файла — проверь соблюдение каждого правила. Формат: [ПРАВИЛО: A-XX] [ФАЙЛ: путь, строка] Нарушение: [что] Критичность: [БЛОКЕР / СРЕДНЕ / МЕЛКО] Фикс: [как привести в соответствие] Статус: ARCH_PASS / ARCH_FAIL / ARCH_WARN / ARCH_SKIP ``` **Если SPEC_FAIL или ARCH_FAIL → фикс → повторить Шаг 1 целиком.** --- ## Шаг 2 — RISK PROFILES После прохождения Шага 1 — **одним сообщением** все профили согласно матрице. S: только 2A (+ 2B если sensitive-bump). M/L: 2A + 2B + 2C параллельно. ### 2A — CODE QUALITY (агент `code-analyzer`) ``` Spec и Architecture проверены. Безопасность и forward-look — другие агенты параллельно, не дублируй. ИЗМЕНЁННЫЕ ФАЙЛЫ: [список] СТЕК / СОГЛАШЕНИЯ: [из CLAUDE.md] A — ЛОГИКА И БАГИ: - Off-by-one, неверные операторы - null / undefined / 0 / NaN / пустые коллекции - async/await без обработки ошибок - Неосмысленные ?? и || дефолты - Возврат не того типа, что ожидает caller B — СОВМЕСТИМОСТЬ С ПРОЕКТОМ: - Конфликты имён, нарушения паттернов проекта - Циклические зависимости, импорты несуществующего - Несоответствия типов с другими частями C — КРАЕВЫЕ СЛУЧАИ ЗДЕСЬ-И-СЕЙЧАС: - Race conditions в одном запросе - Внешний сервис вернул 500 — что сейчас? - Memory leak в одной операции Формат: [ФАЙЛ: путь, строка][Категория: A/B/C] Проблема, сценарий поломки, критичность, фикс. Статус: QUALITY_PASS / QUALITY_FAIL ``` ### 2B — SECURITY (агент `security-auditor`, S при sensitive-bump, M/L всегда) ``` ИЗМЕНЁННЫЕ ФАЙЛЫ: [список] ЧУВСТВИТЕЛЬНЫЕ КОНТЕКСТЫ: [auth, PII, платежи, ЭЦП, …] S1 — INJECTION / UNTRUSTED INPUT (SQL/XSS/cmd/path/SSRF/proto/deserialization) S2 — AUTH / AUTHZ (отсутствие проверок, IDOR, JWT, привилегированные операции) S3 — СЕКРЕТЫ И КРИПТО (hardcoded, MD5, IV, секреты в логах/bundle/responses) S4 — DATA EXPOSURE / PII (поля в ответах, PII в логах, stack traces в prod) S5 — DOS (rate limit, ReDoS, размер парсинга, циклы по user input) S6 — DEPENDENCIES / SUPPLY CHAIN (CVE, абандонированные, URL-imports) S7 — КОНТЕКСТНО-СПЕЦИФИЧНОЕ (webhook signature, ЭЦП цепочка, file upload AV/тип/размер, webhook secret header, user-controlled в job payload) Формат: [ФАЙЛ: путь, строка][Раздел: S1..S7] Класс уязвимости (CWE/OWASP), сценарий эксплуатации, критичность, фикс. Статус: SECURITY_PASS / SECURITY_WARN / SECURITY_FAIL ``` ### 2C — FORWARD LOOK (агент `perf-analyzer`, M/L only) ``` Spec, Quality, Security смотрят «работает ли сейчас». Ты — что сломается под ростом и со временем. ИЗМЕНЁННЫЕ ФАЙЛЫ: [список] ТЕКУЩИЙ ОБЪЁМ: [десятки/сотни/тысячи] ПРОФИЛЬ НАГРУЗКИ: [hot path / cold] ОСЬ A — МАСШТАБ (×10 / ×100): - N+1, отсутствие индексов, full scan - O(n²) на user-controlled размере - Нет пагинации/лимитов - Синхронные внешние API в hot path - Кеши без TTL / unbounded growth ОСЬ B — ВРЕМЯ (через месяц): - Логи/temp/кеши без ротации (диск) - Connection / file handle leaks - Stale data, протухающие кеши/токены - Хардкоднутые даты, истекающие лимиты - Сертификаты с истечением - Schema drift после миграции ОБЯЗАТЕЛЬНО ≥3 точки даже если блокеров нет. Формат: [ОСЬ: A/B][ФАЙЛ: путь, строка] Точка слома, триггер, горизонт, критичность, митигация. Статус: FORWARD_PASS / FORWARD_WARN / FORWARD_FAIL ``` **Если QUALITY_FAIL / SECURITY_FAIL / FORWARD_FAIL → фикс → повторить Шаг 2.** --- ## Шаг 2.5 — ADVERSARIAL SKEPTIC (агент `analyst`) Запускается на L всегда; на M — если суммарно ≥5 находок; на S — пропускается. ``` Ты — Adversarial Skeptic. Не пишешь новых находок. Фильтруешь существующие через project context. Цель — отделить РЕАЛЬНЫЕ риски от теоретических. PROJECT CONTEXT: - Приоритет: [ЗАПУСТИТЬ / ПРОДАТЬ / МАСШТАБИРОВАТЬ] - Объём в первый месяц: [N] - Стадия: [pre-MVP / MVP / production / scale] - Чувствительные контексты: [список] ASSUMPTION LOG ИСПОЛНИТЕЛЯ: [из Шага 0] СПИСОК НАХОДОК: [мерж Quality/Security/Forward] Для каждой находки: 1. РЕАЛЬНО — конкретный сценарий с привязкой к нашим объёмам и стадии. 2. ПАРАНОЯ — теоретически возможно, но при наших объёмах не критично. Правила: - «Теоретически может» без сценария на наших объёмах = ПАРАНОЯ. - «Сломается в первый месяц при заявленной аудитории» = РЕАЛЬНО. - Security CRITICAL/HIGH не может быть параноей — даже на 10 пользователях. - Завышенная критичность — снижай. Заниженная — повышай. Формат: [№][источник][оригинальная критичность] Вердикт: РЕАЛЬНО / ПАРАНОЯ Сценарий или причина пропуска. Финальная критичность. Статус: SKEPTIC_DONE ``` **ПАРАНОЯ-финдинги уходят в WARN-секцию отчёта, не в фиксы.** --- ## Шаг 3 — VERIFICATION & FIX (текущая сессия, всегда) ``` Применяй фиксы только по REAL финдингам. Параноя — в отчёт, не в код. Порядок: SECURITY CRITICAL/HIGH (REAL) → ARCH БЛОКЕР → QUALITY КРИТИЧНО (REAL) → FORWARD КРИТИЧНО (REAL) → SECURITY MEDIUM → QUALITY СРЕДНЕ → FORWARD СРЕДНЕ Правила: - Одно изменение = одна проблема - Запрещён рефакторинг и «пока уже здесь» - Для security-фиксов — добавь негативный тест если есть тест-инфра - Если при фиксе появилась новая проблема — она пройдёт через Шаг 3.5 - Если fixes = 0 — переходи сразу к Шагу 4 (Шаг 3.5 пропустится) ``` --- ## Шаг 3.5 — REGRESSION SWEEP (свежий `reviewer`) Запускается: - L: всегда - M: если применён хотя бы один фикс - S: если ≥3 фикса или хотя бы один security-фикс - На любом размере, если 0 фиксов — пропуск. ``` Не делаешь полного ревью. Смотришь ТОЛЬКО diff фиксов. DIFF ФИКСОВ: [git diff между «до» и «после»] ИСХОДНЫЙ СПИСОК REAL: [для проверки, что закрыто] Ищи: 1. ЧТО НОВОГО — оцени с нуля, под видом фикса могли затащить баг. 2. РЕГРЕССИИ В СОСЕДНЕМ КОДЕ — изменения задели вызывающих? Проверь импорты и вызывающих функций. 3. ФИКТИВНЫЕ ФИКСЫ — закрыта ли исходная проблема, или косметика? Формат: [ФАЙЛ: путь, строка] Тип: [НОВЫЙ БАГ / РЕГРЕССИЯ В СОСЕДНЕМ / ФИКТИВНЫЙ ФИКС] Критичность: [КРИТИЧНО / СРЕДНЕ] Статус: REGRESSION_PASS / REGRESSION_FAIL ``` **REGRESSION_FAIL → фикс новых проблем → повторить Шаг 3.5.** --- ## Шаг 4 — ИТОГОВЫЙ ОТЧЁТ (текущая сессия, всегда) ``` Финальный отчёт фазы [НАЗВАНИЕ]: РАЗМЕР: S / M / L (с обоснованием авто-детекции или пометкой override) ГЕЙТЫ (только запущенные): - Spec: [статус] - Architecture: [статус или SKIPPED-по-размеру / ARCH_SKIP-нет-инвариантов] - Quality: [статус] - Security: [статус или SKIPPED-по-размеру] - Forward: [статус или SKIPPED-по-размеру] - Skeptic: [статус или SKIPPED-по-размеру] - Regression: [статус или SKIPPED-нет-фиксов] ИСПРАВЛЕНО (REAL): - [категория] [проблема] — [что сделано] — [файл:строка] ПАРАНОЯ (Шаг 2.5, если был): - [проблема] — [почему теоретическая] НЕ ИСПРАВЛЕНО (намеренно): - [проблема] — [причина] — [когда вернуться] WATCH-ТОЧКИ ИЗ FORWARD (если был): - [точка] — [горизонт] — [когда мониторить] ЗАТРОНУТЫЕ ФАЙЛЫ ВНЕ ИСХОДНОЙ ФАЗЫ: - [файл] — [почему] ГОТОВНОСТЬ К СЛЕДУЮЩЕЙ ФАЗЕ: ДА / НЕТ ``` --- ## ПРАВИЛА СВЕРХУ **Нельзя:** - Запускать Шаг 2 до прохождения Шага 1 - Запускать Шаг 2.5 до завершения всех ревью Шага 2 - Запускать Шаг 3 до SKEPTIC_DONE (или до завершения Шага 2 если Skeptic пропущен) - Запускать Шаг 3.5 до применения всех фиксов - Использовать текущую сессию как любого Reviewer - Объединять две роли Reviewer'ов в один промпт одному агенту - Запускать параллельные шаги последовательно - Фиксить ПАРАНОЯ-финдинги - Игнорировать sensitive-bump (auth/PII/платежи без security = NO) - Понижать размер ниже авто-детекции без явного override от пользователя - Говорить «готово» без Шага 4 со всеми статусами **Зонирование агентов (фиксированное):** | Шаг | Роль | Агент | Запускается на | |-----|---------------------|--------------------|----------------| | 1A | Spec | `reviewer` | S, M, L | | 1B | Architecture | `system-architect` | M, L | | 2A | Quality | `code-analyzer` | S, M, L | | 2B | Security | `security-auditor` | S(если sens), M, L | | 2C | Forward Look | `perf-analyzer` | M, L | | 2.5 | Skeptic | `analyst` | M(если ≥5), L | | 3 | Fix | session | S, M, L | | 3.5 | Regression | `reviewer` (fresh) | условно (см. матрицу) | | 4 | Final report | session | S, M, L | **Выбор модели:** - Все Reviewer'ы — Opus - Skeptic — Opus обязательно - Regression Sweep — Sonnet достаточно (узкий scope) - На S-размере допустимо Sonnet для Spec/Quality чтобы экономить **Если фаза очень большая (> 15 файлов):** Раздели на блоки по 5-8 связанных файлов. Прогони Шаги 1–3.5 для каждого блока отдельно. Шаг 4 — единый отчёт по всей фазе. --- ## ИНТЕГРАЦИЯ С BULLETPROOF Phase-review предназначен встать **внутри** Bulletproof как Шаг 7 (Review), не заменять Bulletproof. Сопоставление размеров: | Размер задачи | Bulletproof | phase-review | Что запускается | |---------------|-------------|--------------|-----------------| | Bug-fix | S (6 этапов) | S | 2-3 агента, ~30% токенов от L | | Feature | M (10 этапов)| M | 4-6 агентов, ~70% токенов от L | | Architecture | L (12 этапов)| L | 7 агентов, 100% (с батчингом если > 15 файлов) | Размер phase-review **наследуется** от размера Bulletproof по умолчанию. Override возможен в обе стороны — например, на критичную M-фичу с PII можно поставить L-ревью. **Когда phase-review может работать БЕЗ Bulletproof:** - Ad-hoc задача без полного workflow - Внешний код / pull request на ревью - После SPARC-фазы **Когда Bulletproof нужен ВМЕСТО phase-review:** - Задача начинается с нуля (нет реализации, которую можно проверить) - Нужна спецификация / тест-план / документация — это вне scope phase-review --- ## ЧТО ЗАИМСТВОВАНО ИЗ SUPERPOWERS (obra/superpowers) - **Fresh subagent reviewer pattern** — основа всего скилла. - **Subagent-driven development signals** (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED) — для интеграции с агентом-исполнителем фазы. - **Verification before claiming done** — Шаг 4 со статусами всех гейтов. - **Assumption Log** — допущения исполнителя как явный артефакт (Шаг 0 → Шаг 1A → Шаг 2.5). Намеренно НЕ заимствовано: - Brainstorm phase (вне scope верификации). - Pair programming live (наш скилл асинхронный, fresh subagent). - Universal slash-commands от superpowers — у нас своя slash-команда `/phase-review`. --- ## СИГНАЛЫ СУБАГЕНТА-ИСПОЛНИТЕЛЯ Если фаза делалась через Agent tool, исполнитель возвращает один из сигналов: - DONE → запускать Шаг 0 → Шаг 0.5 → дальше по pipeline - DONE_WITH_CONCERNS → прочитать замечания, оценить, потом Шаг 0 - NEEDS_CONTEXT → предоставить контекст и переотправить (ревью не запускать) - BLOCKED → эскалировать в текущую сессию (ревью не запускать) --- ## АВТОМАТИЗАЦИЯ ЧЕРЕЗ STOPHOOK Скилл можно вызывать из StopHook — автозапуск при завершении фазы и передаче управления пользователю. На S-размере overhead минимален (~2-3 агента), поэтому автозапуск экономически оправдан даже для bug-fix'ов.