Plan Skill

---
name: plan-skill
description: "Планирование реализации по методологии superpowers v2: превращает цель в декомпозированный план изменений (HARD-GATE, bite-sized шаги, no placeholders, ветки изменений). GenereIR: brainstorming → writing-plans → executing-plans → verification-before-completion с TDD-шагами Expected FAIL→PASS. Скрипт plan_validator.py проверяет план на готовность к запуску (нет TBD/TODO-заглушек, шаги выполнимы, файлы указаны). Скилл только планирует; исполнение — отдельным режимом по этому же плану. Триггеры: 'спланируй', 'составь план', 'plan', 'как реализовать', 'разбей на шаги', 'roadmap', 'план реализации', 'planning', 'design document', 'technical plan', 'write a plan', 'спланируй разработку'.",
license: MIT
metadata:
  author: best
  version: 1.0.0
compatibility: "Requires Python 3 stdlib for plan_validator.py; runs on any repo"
when_to_use: "Plan an implementation before coding: decomposed steps, acceptance criteria, TDD, no placeholders. Triggers: 'plan', 'спланируй', 'составь план', 'разбей на шаги', 'roadmap', 'technical plan', 'write a plan', 'план реализации'. Example: 'Plan how to implement this feature before I start coding.'"
---

# Plan Skill

> Планирование реализации: из запроса — декомпозированный план изменений,
> готовый к исполнению другим агентом без дополнительных уточнений.

Загружай этот скилл когда нужно **разбить задачу на план шагов** перед тем как
кодировать. Скилл генерирует структурированный план (Markdown-файл) с фазами,
bite-sized шагами, интерфейсами и критериями готовности — и проверяет его
скриптом `plan_validator.py` на отсутствие недоделок (placeholders).

## 🎯 When to use

Use this skill when:
- Есть задача «сделай X», но нужен порядок шагов и критерии готовности
- Просят «спланируй разработку», «разбей на шаги», «составь план»
- Нужен согласованный процесс: обсуждение → план → исполнение → проверка
- Начинается новый этап: позбюжетные скиллы, фиц, рефакторинг, интеграция
- Нужно одноэлементное ТЗ для передачи параллельным агентам

Do NOT use when:
- Нужно только объяснить, как работает код — это explore/knowledge, не планирование
- Задача тривиальная: один файл, однозначное изменение — можно без плана
- Нужно открытого исполнения: провалидируй запрос, потом вызывай агента-coder

## 📦 Files

- `SKILL.md` — этот файл
- `scripts/plan_validator.py` — проверка плана на готовность (stdlib only)
- `templates/implementation-plan.md` — шаблон плана реализации
- `examples/plan-example.md` — пример готового плана

## 🔧 Workflow

### Фаза 0 — Brainstorming (обзор запроса)
1. Уточни **цель** (что получить) и **границы** (что НЕ входит).
2. Проверь код если нужно: `codegraph_explore` / чтение ключевых файлов.
3. Зафиксируй входные интерфейсы (что уже есть) и целевое состояние.
4. Определи риски: ломающие изменения, скрытые зависимости, конфликты.

### Фаза 1 — Writing the plan (составление)
1. Создай файл плана по шаблону: `docs/plans/<slug>-<date>.md` или в корне как
   `PLAN.md`. Путь любой, главное — единый файл.
2. Структура плана:
   - **Goal** — цель одним предложением + acceptance criteria (проверяемые).
   - **Constraints** — запреты: «не трогать X», «stdlib only», «без новых зависимостей».
   - **Steps** — неделимые bite-sized шаги, каждый с файлом и ожидаемым результатом.
   - **Interfaces** — каждый шаг с `Produces:` / `Consumes:` (что выходит, что входит).
   - **Verification** — как проверяем каждый шаг (команда, тест, ожидаемый вывод).
3. Применяй TDD-стиль где уместно: шаг «пишем тест → Expected FAIL», затем
   «реализация → PASS».
4. Правило **No placeholders**: в плане не должно быть `TODO`, `TBD`, `...`,
   нерешительного «решим потом». Если неясно — реши сейчас или вынеси вопрос пользователю.
5. Правило **HARD-GATE**: не переходи к коду, пока план не одобрен (пользователем
   или рулевой ролью) и не прошёл валидацию части важно.

### Фаза 2 — Validate the plan
1. Прогони `python3 scripts/plan_validator.py <plan-file>`.
2. Скрипт проверяет: наличие Goal/Constraints/Steps, отсутствие заглушек (TBD/TODO/`...`),
   наличие файлов-целей, размер шагов (не гигантских), consistency секций.
3. Вывод типа: `✅ Plan <path> is execution-ready` или список замечаний.
4. Пока валидатор не зелён — план не готов к исполнению.

### Фаза 3 — Execute (исполнение)
1. Исполняющий агент действует строго по шагам плана, отмечая `[x]`.
2. После каждого шага — минимальная сверка: тесты/диагностика для «Done».
3. Каждый шаг реализует интерфейс из плана: не расширять объём (scope creep).
4. Итог — отчёт: какие шаги сделаны, какие НЕ и почему, что проверил.

### Фаза 4 — Verification (проверка до завершения)
1. Прогони тесты/линтер/сборку (по контексту проекта).
2. Сверь результат с Goal и acceptance criteria: всё выполнимо observable подтверждено.
3. Если стоит ревью: запусти `code-review` (скилл репозитория).
4. Не завершай работу «на словах» — только после прохождения проверки.

## 🛡 Red flags (красные флаги плана)
- Шаг крупнее «одного действия» (можно разбить) — разбери на подшаги.
- В плане есть TODO/TBD/«в процессе» — валидатор должен поймать это.
- Скилл вызывает код, которого нет в плане (Interfaces не свяпываются).
- Acceptance criteria невозможно проверить (субъективны) — ужесточи формулировки.
- План на N файлов, а реализация вышла в 3 раза больше — планируй атомарно.

## ✅ Definition of Done
- План сохранён в Markdown, прошёл `plan_validator.py`.
- Каждый шаг: файл/границы + Produces/Consumes + Verification.
- Нет заглушек и неоднозначностей. Список замечаний валидатора пуст.
- Пользователь одобрил план (или явно делегировал исполнителю).