phase-review

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'ов.