Plan Review

<!-- BSV — Brief Skill View | поиск: BSV
Скил   : plan-review
TL;DR  : Структурированная аннотация плана агента — до того как он начнёт писать код
Вызов  : /plan-review, "проверь план", "review plan", "покажи план", "аннотируй план"
НЕ для : Ревью уже написанного кода — для этого /review-squad. Только планы.
-->

---
name: plan-review
description: >
  [STATUS: review] [CONFIDENCE: high] [REVIEWED: 2026-04-30]
  Адаптировано из Plannotator (backnotprop/plannotator, 4776 ⭐).
  Структурированный human-in-the-loop review план агента перед выполнением.
  Агент показывает план → человек аннотирует (DELETE/COMMENT/KEEP) →
  структурированный фидбек возвращается → агент пересматривает или продолжает.
  Триггеры: /plan-review, "проверь план", "review plan", "покажи план перед началом",
  "аннотируй план", "хочу проверить план", "plan approval".
  НЕ использовать для: ревью кода — только планы/roadmap/архитектурные решения.
---

# Plan Review — Структурированная аннотация плана

Human-in-the-loop checkpoint между plan-mode и execution.
Агент не начинает писать код пока план не апрувнут.

## Когда использовать

- Перед задачей на 3+ файла (обязательно по CLAUDE.md)
- Перед архитектурным изменением
- Когда план кажется слишком широким или непонятным
- После `EnterPlanMode` → перед `ExitPlanMode`

## Протокол (4 шага)

### Шаг 1 — Агент показывает план с нумерацией

Агент ОБЯЗАН показать план в следующем формате:

```markdown
# План: [название задачи]

**Файлы:** N файлов | **Риск:** LOW/MEDIUM/HIGH | **Время:** ~X мин

## Kill Condition
> "Этот план провален если ______."
> *(обязательно для 5+ файлов / HIGH риска)*

## Шаги
[1] <действие> → <файл/артефакт>
[2] <действие> → <файл/артефакт>
[3] <действие> → <файл/артефакт>
...

## Что НЕ входит в план
- <явные границы>

## Риски
- <что может пойти не так>
```

### Шаг 2 — Человек аннотирует

Используй три команды:

| Команда | Синтаксис | Что делает |
|---------|-----------|------------|
| `del [N]` | `del 3` | Удалить шаг N из плана |
| `edit [N] <текст>` | `edit 2 использовать batch вместо loop` | Изменить шаг N |
| `add [после N] <текст>` | `add после 3 запустить тесты` | Добавить шаг после N |
| `comment <текст>` | `comment масштаб слишком большой` | Глобальный комментарий |
| `kill <условие>` | `kill если тесты упали > 3` | Установить/изменить Kill Condition |
| `ok` | `ok` | Апрув плана, продолжай |
| `stop` | `stop` | Отклонить план, переделай |

**Пример сессии аннотации:**
```
del 4
edit 2 использовать рекурсивный обход вместо flat
comment сначала напиши тесты
ok
```

### Шаг 3 — Агент применяет фидбек

Агент читает аннотации и:
- `del N` → убирает шаг из плана, сдвигает нумерацию
- `edit N <текст>` → заменяет описание шага
- `add после N <текст>` → вставляет новый шаг
- `comment <текст>` → учитывает как глобальный constraint
- После применения — показывает **пересмотренный план**
- При `ok` — начинает выполнение
- При `stop` — возвращается к планированию с нуля

### Шаг 4 — Подтверждение и выполнение

После апрува агент пишет:
```
✅ План апрувнут. Начинаю выполнение.
Шаги: [1] → [2] → [3] → ...
```

## Структура фидбека (для агента)

После аннотации агент получает следующий структурированный фидбек:

```markdown
# Plan Feedback

Аннотировано: N изменений.

## Удалить
- [Шаг N] <текст шага>
  > Причина: <что написал пользователь или "удалить без объяснений">

## Изменить
- [Шаг N] Было: <оригинал>
  > Стало: <новый текст>

## Добавить
- [После шага N] <новый шаг>

## Глобальные комментарии
> <comment текст>

---
Итог: APPROVE / DENY / REVISE
```

## Интеграция с plan_mode_guard.py

Наш `plan_mode_guard.py` алертит на milestone (3, 5, 10, 20... файлов).
Plan-review — следующий уровень: не просто предупреждение, а полный review loop.

**Рекомендуемый workflow:**
```
EnterPlanMode
    ↓
plan_mode_guard алерт (milestone)
    ↓
/plan-review — аннотация человеком
    ↓
ExitPlanMode → выполнение
```

## SNR Gate перед plan-review

Перед глубоким review стоит проверить:
```
/snr Agent Gate → план имеет высокий SNR → /plan-review
```

Если SNR < 2 (шум превышает сигнал) → план пересмотреть до review.

## Промпт для быстрого запуска

```
/plan-review

Покажи план в формате с нумерацией, рисками и явными границами.
Жди моих аннотаций перед тем как начать выполнение.
```

## Пример полной сессии

```
Пользователь: /plan-review

Агент:
# План: добавить anti-distortion hook

**Файлы:** 3 файла | **Риск:** LOW | **Время:** ~20 мин

## Шаги
[1] Добавить _DISTORTION_PATTERNS в session_save.py
[2] Написать _check_distortion() функцию
[3] Интегрировать в _build_wiki_entry()
[4] Добавить 9 тестов в test_session_hooks.py
[5] Зарегистрировать в skills/registry.yaml

## Что НЕ входит
- UI изменения
- CI/CD конфиг

## Риски
- Regex ложные срабатывания на scoped statistics

---
Пользователь:
del 5
edit 4 добавить 5 тестов минимум, не 9
kill если после рефактора падает > 0 тестов — откат
comment сначала RED тесты, потом код
ok

---
Агент:
# Пересмотренный план

## Kill Condition
> "План провален если после рефактора падает > 0 тестов — откат."

[1] Добавить _DISTORTION_PATTERNS в session_save.py
[2] Написать _check_distortion() функцию
[3] Интегрировать в _build_wiki_entry()
[4] Добавить 5+ тестов (RED first) в test_session_hooks.py

Глобально: TDD порядок — тесты перед кодом.

✅ Апрув получен. Начинаю с [4] RED тестов.
```

## Gotchas

- Без `/plan-review` агент часто пропускает edge cases в плане — review занимает 2 мин, а исправление 2 часа
- `stop` даёт агенту возможность переосмыслить подход полностью — используй когда план идёт в неправильном направлении
- `comment` без `ok`/`stop` — агент ждёт финального решения, не начинает
- Большие планы (10+ шагов) — дели на фазы, review каждую фазу отдельно