--- name: resolve description: "Взять одну задачу и довести её до закрытия. Одна точка входа, два сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ решения известен — сценарий решения: цикл Spec Driven Development (opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие). Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → вычитка написанного → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст. Использовать, когда просят взять, сделать или решить задачу, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога." --- # Работа над одной задачей Проводит **одну** задачу от постановки до закрытия. Вокруг планового стопа — без согласований: механику не обсуждаем, делаем. **Сценария два, а точка входа одна.** Какой из них идёт, решает **скилл**, прочитав постановку, а не человек до вызова: «есть ли у задачи очевидный способ решения» видно после чтения записи, и требовать этого суждения от вызывающего значит требовать его раньше, чем оно возможно. | Сценарий | Когда | Чем кончается | | --- | --- | --- | | **решение** | способ известен, спорно только как | код, ревью, архив, коммит, закрытие | | **разведка** | способа нет: тип `research`, сырая идея, мутная постановка | ответ в документах, задачи, коммит, закрытие | Ход каждого сценария живёт своим справочником: **решение** — [references/solve.md](references/solve.md), **разведка** — [references/research.md](references/research.md). Здесь только общее: вход, развилка, правила, которые не зависят от сценария. Сценарии лежат порознь и одинаково, потому что привилегированного среди них нет: тот, что жил бы прямо здесь, читался бы как основной, а второй — как оговорка. ## Предпосылки - **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка сценария решения**, а не опция. На них стоят его шаги 2, 6 и 8, проход `review-specs` и ревью дизайна (они завязаны на `openspec/changes//specs/*/spec.md` и на `openspec validate --strict`). **Проект без OpenSpec этим скиллом не ведётся** — подключай OpenSpec, а не вырождай цикл сценария; почему ветка деградации здесь не пишется, сказано в `av-dev-code:review`, раздел «Предпосылки», и дом у этого довода там. Заводить руками не надо: каталог и настройку в `config.yaml` делает скилл `av-dev-code:openspec`. **Сценарию разведки OpenSpec не нужен** — она не заводит change; `opsx:explore` берётся, если плагин есть. - **Проектные копии этих скиллов и агентов удаляются при установке плагина** (`.claude/skills/` — голые имена `resolve`, `review`, а у проектов прошлого поколения ещё `task-pipeline`, `review-pipeline`, `task-batch`, и с префиксом проекта: `<проект>-task-pipeline`, `<проект>-review-pipeline`; `.claude/agents/<проект>-review-*.md`). Две копии одного скилла расходятся, и побеждает та, что короче названа. ### Обращение к соседним плагинам **Копия.** Дом — `shared/plugin-boundary.md` в репозитории плагинов: правило общее для всех, кто зовёт чужое, и ни один плагин им не владеет. Правится дом, а не этот файл. Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на месте. **Чужой скилл зовётся полным именем** — `av-dev-docs:canon`, `av-dev-tasks:tasks`, `av-dev-code:review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. **Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его сам. **Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя, пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже. **Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня установленных плагинов проект не ведёт — он разошёлся бы с действительностью молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.docs.json` — канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер. Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего формата: у канона документов и у каталога задач они свои и двигаются порознь. Скилл зовёт `av-dev-code:review`, `av-dev-docs:docs` и `av-dev-tasks:tasks`. Чем оборачивается отсутствие каждого — на самих шагах и в разделе «Границы». Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта, объёмы, модель угроз, прецеденты, — живут в **документах канона** `av-dev-docs`; карта «что где» — `references/project-facts.md` конвейера ревью. **Документов канона нет — проект к нему не приведён.** Скажи это строкой и предложи скилл `av-dev-docs:canon`: одна операция на проект против поразрядной деградации на каждой задаче. Работу при этом не останавливай. ## Вход Задача задаётся **путём к файлу, именем файла, слагом или просто текстом**. Ничего из этого не задано — попроси у вызывающего и остановись; сам в беклог не лезь и приоритеты не интерпретируй: что делать дальше, решает не этот скилл. **Запись из каталога сперва проверяется на готовность, и проверяет её машина.** Вызови Skill `av-dev-tasks:tasks` и попроси прогнать `ready <слаг>`: он смотрит тип, цель у `feature`, пустой ли раздел вопросов и собраны ли разделы схемы типа. Судить это глазами нельзя — ровно тот случай, где машина дешевле и точнее, а цена ошибки отложенная: недостающие критерии приёмки обнаружатся на приёмке, когда сверять уже не с чем. **`ready` отказал — это исход, а не препятствие для тебя.** Скажи, чего не хватает, и остановись: дописывать чужую запись за автора не твоя работа. Исход — «не доведена», с названной причиной. **Отказ `ready` сценарий не выбирает.** Запись `research` без раздела «Вопрос» (сырьё) — отказ и здесь: у неё нет вопроса, и разведывать нечего. Плагина `av-dev-tasks` в проекте нет или задача пришла текстом — прогонять нечего. Тогда прочитай постановку сам и скажи строкой, что готовность машиной не проверялась; работу при этом не останавливай. ## Развилка: какой сценарий Она одна, и стоит до всякой работы: **есть ли у задачи один очевидный способ решения?** - **есть** — что делать, понятно; спорно только как. **Сценарий решения** — [references/solve.md](references/solve.md); - **нет** — тип `research`, сырая идея, новое и незнакомое, мутная постановка, два подхода с разной ценой. **Сценарий разведки** — [references/research.md](references/research.md). Признак не в объёме работы. Крупная задача с очевидным способом идёт в решение; маленькая, но незнакомая — в разведку. Тип `research` в разведку идёт всегда: её исход знание, а не изменение системы. **Назови выбранный сценарий вслух первой репликой** — одной строкой, с причиной. Молча выбранный сценарий человек обнаруживает по тому, что работа пошла не туда, и обнаруживает поздно. ### Сценарий выбирается один раз **Смена сценария по ходу — событие, а не тихий поворот**, и каждая из двух смен устроена по-своему: - **решение → разведка**: обнаружилось, что очевидного способа нет. Это **стоп** с исходом «нужна разведка»: назови, что именно неясно, и не продолжай. Кода к этому моменту не написано, и писать его «пока разбираемся» нельзя; - **разведка → решение**: способ выбран на чекпоинте вариантов. Разведка **всё равно доводится до конца** — ответ записан, задачи уточнены, коммит сделан, — и решение идёт **следующим прогоном**, который запускает человек. **Соблазн «разведаю по ходу» живёт именно здесь**, и он дорог тем, что выглядит экономией одного прогона. Разведка внутри решения не имеет своего чекпоинта: выбор делается тем, кто уже начал писать, и человек видит его только в объяснении, где обсуждать выбор поздно. Ровно за это сценарии и разведены — не за то, что это разные работы, а за то, что у них разные моменты для человека. ```mermaid flowchart TD in["вход: файл, слаг или текст"] ready["ready: готовность записи
av-dev-tasks:tasks"] fork{"есть очевидный
способ решения?"} solve["сценарий решения
references/solve.md
код, ревью, архив, коммит"] res["сценарий разведки
references/research.md
ответ в документы и задачи"] in --> ready --> fork fork -->|"да"| solve fork -->|"нет"| res solve -.->|"способа всё же нет:
стоп, кода не написано"| res res -.->|"способ выбран:
следующим прогоном,
зовёт человек"| solve ``` Схема — **сводка**: содержание сценариев в их справочниках, и при расхождении прав справочник. ## Автономность и плановый стоп **У каждого сценария ровно один плановый стоп**, и стоят они в разных местах: у решения — объяснение после ревью дизайна, у разведки — варианты до первого написанного требования. Правило вокруг них общее. **Вокруг чекпоинта умолчание прежнее — делать, а не спрашивать.** Чекпоинт не отменяет автономность, он даёт развилкам плановое место, куда копиться. Разрез простой: - развилка найдена **до** чекпоинта — она его и ждёт. Не спрашивай отдельно: чекпоинт рядом и стоит дёшево, а три вопроса подряд стоят дороже одного разговора; - развилка найдена **после** чекпоинта — старое правило: **запиши вопрос и доведи остаток**, не останавливаясь. Запись вопроса устроена так: 1. **Запиши там, где проект держит вопросы** (секция беклога, файл задачи, трекер — это знает проект). Проект не сказал, куда, — отдельной секцией `Вопросы` в своём докладе, и это тоже исход. Тело отвечает на три вещи: **что именно решить**, **какие есть варианты и цена каждого**, **что стоит, пока решения нет**. Плюс твоя рекомендация — человек чаще соглашается, чем выбирает заново, и готовое суждение экономит ему весь контекст. 2. **Переформулируй задачу на остаток** — то, что делается без этого решения. Назови границу: докуда доводим сейчас. 3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана в объявленных границах. В разведке остаток — это ответ в объявленных рамках: что успели узнать, где остановились и почему. **Что остатком не является — правило живёт не здесь.** Канонический текст с обеими оговорками — в плагине `av-dev-tasks`, скилл `av-dev-tasks:groom`, раздел `## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания». Правило принадлежит управлению задачами, потому что решает **сделана задача или вышла**, — это исход планирования, а не исполнения. **Ссылайся, не пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и потеряла из перечня самое необратимое — запись **наружу**. Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами — **материализация нерешённого** (запись состояния, зависящего от неотвеченного вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке). Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход «не доведена». Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было — в хранилище, в журнал, в витрину или наружу, — спрашивай человека. Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос записан, ничего не коммитится наполовину. ### Когда спрашивать вне чекпоинта По другому основанию — не «сложное решение», а **необратимое действие**: - деплой, выкладка наружу, смена публичного адреса или токенов; - удаление или перезапись рабочих данных, включая подрезку архивов; - всё, что уходит за пределы машины. Здесь ошибка не откатывается коммитом, поэтому спрашиваем даже когда решение кажется очевидным. ## Границы: чем этот скилл не владеет - **Беклогом, целями и приоритетами.** Задача приходит извне. Скилл её не выбирает, не приоритизирует, не заводит и не переоценивает. - **Форматом задач и документов.** Индексы и документы канона руками не правятся, путь к чужому скрипту не выдумывается: этим владеют `av-dev-tasks:tasks` и `av-dev-docs:docs`. Закрытие — работа этого скилла, и это осознанное решение с названной ценой: **приёмщик и исполнитель совпали**. Закрытие поэтому **не окончательно** — человек на груминге (`av-dev-tasks:groom`) возвращает задачу `reopen` с причиной, а доклад по критериям приёмки становится единственным, по чему приёмка вообще возможна. - **Определением ценности.** «Нужна ли эта функциональность» — не вопрос этого скилла ни на одном шаге и ни в одном сценарии. Чекпоинт решения спрашивает «так ли решаем», чекпоинт разведки — «каким из способов», но не «надо ли». Что не принадлежит **отдельному сценарию**, названо у него же: урожай ревью и выбор способа — в [solve.md](references/solve.md), код и приоритет — в [research.md](references/research.md). ## Наблюдаемые исходы **У каждого сценария их четыре**, и живут они у сценария: [решение](references/solve.md) — сделана, не доведена, оказалась крупнее задачи, нужна разведка; [разведка](references/research.md) — способ выбран, знание записано, отказ, не доведена. Общего исхода нет намеренно. «Сделана» у решения и «знание записано» у разведки — разные вещи с разной приёмкой, и слово, накрывающее оба, скрывало бы именно то, чем прогон кончился. ## Доклад Ядро общее, и в нём обязательно: - **какой сценарий шёл** — решение или разведка, — и почему выбран он; - **исход** одним из четырёх слов своего сценария и, если он не благополучный, чем ограничен результат; - что сделано, какие вопросы записаны и куда; - чего проверить или узнать **не удалось**. Сверх ядра каждый сценарий добавляет своё: [solve.md](references/solve.md) — чекпоинт, change, критерии приёмки, урожай и границы покрытия; [research.md](references/research.md) — вопрос и ответ, адреса записи, заведённые задачи, рамки. ## Тонкости - **Не завязывайся на основную ветку и корень репозитория.** Скилл работает в текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не создавай веток, не пушь. - Прогон проходит **один** чекпоинт, и это норма, а не упрощение. Два стопа за одну задачу — цена незнания способа, и платится она двумя прогонами, а не одним длинным. - Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси подтверждать механику: чекпоинт — единственное место, где ждут ответа. - **Сценарий назван вслух — значит, его можно оспорить.** Человек, увидевший в первой реплике «иду разведкой, потому что способа не видно», поправит выбор одной фразой; молча выбранный сценарий он поправит через полчаса работы.