task-understanding

---
name: task-understanding
description: Use when starting any non-trivial task (new feature, project, refactor, migration, script, behavior change, vague request) — before planning or writing code. Используй, когда начинается любая нетривиальная задача: сначала выясни недостающий контекст и критерии результата, потом напиши подробный план файлом.
---

# Понимание задачи и подробный план

## Ядро

Пользователь описывает задачу словами, и в этих словах всегда есть дырки. Он их не
замечает, потому что у него в голове картинка уже есть. Твоя работа — достать эту
картинку вопросами, а не достроить её догадками.

Два провала, которые этот скил закрывает:

1. **Мало вопросов.** Спросить 2 штуки «для приличия» и угадать остальное.
2. **План-оглавление.** Выдать 7 строк «каркас, клиент API, хранилище, деплой» и
   назвать это планом. Это не план: по нему нельзя работать и нельзя проверить результат.

## Когда применяется

По умолчанию — к любой задаче, кроме тривиальной.

**Тривиальная** — та, где нечего решать: опечатка, переименование, одна строка без
изменения поведения, ответ на вопрос о коде, запуск готовой команды.

**Нетривиальная** — всё остальное: новая фича, новый проект, рефакторинг, миграция,
скрипт автоматизации, изменение поведения, «сделай по-человечески», «добавь нормально».

Сомневаешься — считай нетривиальной. Цена лишнего вопроса — минута. Цена неверного
плана — переделка всего.

## Железное правило

Пока не выполнено всё три пункта, код и файлы проекта не создаются:

1. Задан пакет вопросов (5–8) **или** явно показано, что дырок нет.
2. Создан файл плана.
3. Пользователь не отверг план.

Читать, искать, запускать `ls`/`grep`/тесты — можно и нужно в любой момент.

## Шаг 0. Сначала посмотри, потом спрашивай

Вопрос, ответ на который лежит в репозитории, — это потерянное доверие.

Прочитай: `AGENTS.md`/`CLAUDE.md`, `README`, структуру проекта, конфиги, зависимости,
последние коммиты, код рядом с местом изменения. Найди, как эта штука работает сейчас.

Никогда не спрашивай: какой стек, какая база, есть ли тесты, как называется файл —
если это можно увидеть. Спрашивай только то, чего в проекте физически нет: намерения,
приоритеты, ограничения, критерии «хорошо».

Если доступа к коду нет (пустая папка, нет пути) — это первый вопрос, а не догадка.

## Шаг 1. Найди дырки

Пройди чек-лист и для каждого пункта отметь: **известно / догадка / дырка**.

| Пункт | Что нужно понять |
|---|---|
| Зачем | Какую боль решаем, что изменится в жизни пользователя |
| Для кого | Кто пользуется, сколько людей, какой уровень подготовки |
| Результат | Что должно работать в конце, как пользователь это увидит |
| Приёмка | По какому наблюдаемому признаку считаем «готово» |
| Границы | Что в эту задачу **не** входит |
| Ограничения | Стек, среда, хостинг, сроки, деньги, лицензии, доступы |
| Данные | Откуда берутся, чьи, что с приватностью, что при пустых/битых |
| Риски | Что дороже всего переделывать, что необратимо |
| Проверка | Чем и как докажем, что работает |
| Уже есть | Что пробовали, что не понравилось, что нельзя менять |

Вопросы задаются **только по дыркам**, и только по тем, чей ответ меняет то, что
будет построено. Дырка, где любой ответ ведёт к одному и тому же коду, — не дырка.

## Шаг 2. Пакет вопросов: 5–8 штук

Сначала одна-две строки «как я понял» — чтобы пользователь увидел, где ты уже
промахнулся. Потом вопросы.

Правила каждого вопроса:

- один вопрос — одна тема, нумерация;
- конкретика вместо абстракции: «от 250к на руки или процент от текущей?» лучше, чем
  «какие требования к зарплате?»;
- скажи, что изменится от ответа: «от этого зависит, нужен ли сервер»;
- предложи свой дефолт: «(если промолчишь — возьму 250к и отброшу вакансии без вилки)»;
- где можешь — дай 2–3 варианта на выбор, а не открытый вопрос.

Заканчивай одной строкой: «Отвечай по номерам, можно коротко».

Меньше 5 вопросов — нормально **только** если дырок реально меньше; тогда напиши,
какие пункты чек-листа закрыты и чем. Больше 8 — режь до тех, что меняют план.

## Шаг 3. Второй раунд — добивка

После ответов пройди чек-лист заново. Появились новые дырки, меняющие план, — задай
до 3 вопросов одним сообщением.

Если ответы открыли развилку (два-три реальных способа сделать), не выбирай молча:
покажи варианты, по одному абзацу на каждый, с ценой каждого, порекомендуй один и
спроси, какой берём. Выбор подхода — решение пользователя, не твоё.

## Шаг 4. План файлом

Путь: `docs/plans/YYYY-MM-DD-<короткое-имя>.md`. Нет репозитория — `plans/` в текущей
папке. Путь назови в чате до того, как начнёшь писать.

Обязательные разделы, в этом порядке:

```markdown
# <Название> — план

## 1. Понимание задачи
Что делаем, для кого, зачем. 2–5 строк.

## 2. Критерии приёмки
- [ ] Наблюдаемое утверждение, которое можно проверить командой или глазами
- [ ] ...

## 3. Что НЕ входит
Явный список, чтобы объём не пополз.

## 4. Допущения
| # | Допущение | Если не так — что меняется |
|---|---|---|

## 5. Открытые вопросы
Что осталось неясным, какой дефолт выбран и почему это терпит.

## 6. Подход
Какие варианты рассматривались, что выбрано и почему.

## 7. Файлы
| Файл | Создать/изменить | Ответственность |
|---|---|---|

## 8. Задачи
(формат ниже)

## 9. Риски
| Риск | Вероятность | Чем ловим |
|---|---|---|

## 10. Финальная проверка
Пошаговый сценарий: команды и ожидаемый результат целиком, не по кускам.

## 11. Если что-то пошло не так
Признак → что делать. Для необратимых шагов (миграции, удаление) — план отката.
```

Формат задачи:

```markdown
### Задача N: <глагол + объект>

Цель: одно предложение.
Файлы: `path/a.ts`, `path/b.ts`

Шаги:
- [ ] Действие → проверяемый результат
- [ ] Действие → проверяемый результат

Проверка: `<команда>` → ожидаемо <что видим>
Готово, когда: <наблюдаемое условие>
```

Требования к задачам:

- каждая задача даёт самостоятельно проверяемый результат;
- у каждой есть «Готово, когда» — без него задача не считается задачей;
- запрещены формулировки без измерения: «улучшить», «настроить», «отрефакторить»,
  «сделать нормально». Заменяй на наблюдаемое: «p95 < 300 мс», «0 ошибок в логе»,
  «токен живёт 15 минут и обновляется по /refresh»;
- порядок задач — такой, чтобы после каждой проект оставался рабочим;
- зависимости между задачами указаны явно.

## Шаг 5. Стыковка с writing-plans

Этот скил владеет вопросами и контрактом плана. `writing-plans` владеет нарезкой на
шаги и TDD-порядком. После ответов на вопросы:

1. Загрузи `writing-plans` и следуй ему для нарезки задач.
2. Дополни его результат недостающими разделами 1–5, 9–11. Не переписывай то, что
   он уже сделал хорошо.
3. Сохрани одним файлом по пути из шага 4.

`brainstorming` не запускай: пользователь выбрал режим «только план файлом», без
отдельной спеки и без согласования дизайн-документа. Это его постоянное предпочтение.

## Если пользователь молчит или сказал «решай сам»

Молчание — это когда вопрос **задан**, а ответа нет. Если ты сам решил не спрашивать —
это не молчание, это пропущенный шаг 2.

Не блокируй работу и не угадывай молча.

1. Выбери дефолт по каждому открытому вопросу.
2. Внеси его в раздел «Допущения» с последствием, если не так.
3. Пометь план: `ЧЕРНОВИК: N допущений, требуют подтверждения`.
4. Продолжай. Одно короткое сообщение в конце: «взял такие-то допущения, поправь если что».

## Красные флаги

| Мысль | Реальность |
|---|---|
| «Задача понятна, вопросы лишние» | Понятна тебе. Пользователь имел в виду другое — узнаешь через неделю переделки. |
| «Спрошу 2 вопроса для приличия» | Пользователь прямо жалуется на это. 5–8 по дыркам. |
| «План из 8 пунктов — достаточно» | Это оглавление. Нужны задачи с проверкой и «Готово, когда». |
| «Пользователь спешит, спрошу потом» | Потом — это после кода. Тогда вопросы превращаются в переделки. |
| «Спрошу, какой стек» | Посмотри в репозиторий. Спрашивай только намерения. |
| «Сделаю сначала, покажу — быстрее» | Быстрее только в первый раз. Дальше — три переделки. |
| «Критерии успеха очевидны» | Очевидны тебе. Запиши их — это единственный способ проверить «готово». |
| «Отвечу за пользователя, он же занят» | Тогда это допущение в плане, а не тишина. |

## Самопроверка перед отправкой плана

- [ ] Репозиторий/контекст прочитан, вопросы не дублируют известное
- [ ] Задано 5–8 вопросов (или обосновано меньше)
- [ ] Был второй раунд добивки
- [ ] Критерии приёмки проверяемы
- [ ] Есть «Что НЕ входит»
- [ ] Каждое допущение помечено и имеет последствие
- [ ] У каждой задачи есть «Готово, когда»
- [ ] Есть финальная проверка целиком
- [ ] План сохранён файлом, путь назван в чате

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 4 KB
• README.ru.md 6 KB
• SKILL.md 14 KB
• install.sh 1 KB