Plan Skill

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.
• Нет заглушек и неоднозначностей. Список замечаний валидатора пуст.
• Пользователь одобрил план (или явно делегировал исполнителю).