dev-skills/av-dev-code/skills/resolve/SKILL.md

name, description

name

description

resolve

Взять одну задачу и довести её до закрытия. Одна точка входа, два сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ решения известен — сценарий решения: цикл Spec Driven Development (opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие). Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → вычитка написанного → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст. Использовать, когда просят взять, сделать или решить задачу, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога.

Работа над одной задачей

Проводит одну задачу от постановки до закрытия. Вокруг планового стопа — без согласований: механику не обсуждаем, делаем.

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

Сценарий	Когда	Чем кончается
решение	способ известен, спорно только как	код, ревью, архив, коммит, закрытие
разведка	способа нет: тип research, сырая идея, мутная постановка	ответ в документах, задачи, коммит, закрытие

Ход каждого сценария живёт своим справочником: решение — references/solve.md, разведка — references/research.md. Здесь только общее: вход, развилка, правила, которые не зависят от сценария. Сценарии лежат порознь и одинаково, потому что привилегированного среди них нет: тот, что жил бы прямо здесь, читался бы как основной, а второй — как оговорка.

Предпосылки

• OpenSpec и скиллы opsx:* — жёсткая предпосылка сценария решения, а не опция. На них стоят его шаги 2, 6 и 8, проход review-specs и ревью дизайна (они завязаны на openspec/changes/<id>/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;
• нет — тип research, сырая идея, новое и незнакомое, мутная постановка, два подхода с разной ценой. Сценарий разведки — references/research.md.

Признак не в объёме работы. Крупная задача с очевидным способом идёт в решение; маленькая, но незнакомая — в разведку. Тип research в разведку идёт всегда: её исход знание, а не изменение системы.

Назови выбранный сценарий вслух первой репликой — одной строкой, с причиной. Молча выбранный сценарий человек обнаруживает по тому, что работа пошла не туда, и обнаруживает поздно.

Сценарий выбирается один раз

Смена сценария по ходу — событие, а не тихий поворот, и каждая из двух смен устроена по-своему:

• решение → разведка: обнаружилось, что очевидного способа нет. Это стоп с исходом «нужна разведка»: назови, что именно неясно, и не продолжай. Кода к этому моменту не написано, и писать его «пока разбираемся» нельзя;
• разведка → решение: способ выбран на чекпоинте вариантов. Разведка всё равно доводится до конца — ответ записан, задачи уточнены, коммит сделан, — и решение идёт следующим прогоном, который запускает человек.

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

flowchart TD
    in["вход: файл, слаг или текст"]
    ready["ready: готовность записи<br/>av-dev-tasks:tasks"]
    fork{"есть очевидный<br/>способ решения?"}
    solve["сценарий решения<br/>references/solve.md<br/>код, ревью, архив, коммит"]
    res["сценарий разведки<br/>references/research.md<br/>ответ в документы и задачи"]

    in --> ready --> fork
    fork -->|"да"| solve
    fork -->|"нет"| res
    solve -.->|"способа всё же нет:<br/>стоп, кода не написано"| res
    res -.->|"способ выбран:<br/>следующим прогоном,<br/>зовёт человек"| 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, код и приоритет — в research.md.

Наблюдаемые исходы

У каждого сценария их четыре, и живут они у сценария: решение — сделана, не доведена, оказалась крупнее задачи, нужна разведка; разведка — способ выбран, знание записано, отказ, не доведена.

Общего исхода нет намеренно. «Сделана» у решения и «знание записано» у разведки — разные вещи с разной приёмкой, и слово, накрывающее оба, скрывало бы именно то, чем прогон кончился.

Доклад

Ядро общее, и в нём обязательно:

• какой сценарий шёл — решение или разведка, — и почему выбран он;
• исход одним из четырёх слов своего сценария и, если он не благополучный, чем ограничен результат;
• что сделано, какие вопросы записаны и куда;
• чего проверить или узнать не удалось.

Сверх ядра каждый сценарий добавляет своё: solve.md — чекпоинт, change, критерии приёмки, урожай и границы покрытия; research.md — вопрос и ответ, адреса записи, заведённые задачи, рамки.

Тонкости

• Не завязывайся на основную ветку и корень репозитория. Скилл работает в текущем worktree и на текущей ветке: не делай git checkout/switch, не создавай веток, не пушь.
• Прогон проходит один чекпоинт, и это норма, а не упрощение. Два стопа за одну задачу — цена незнания способа, и платится она двумя прогонами, а не одним длинным.
• Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси подтверждать механику: чекпоинт — единственное место, где ждут ответа.
• Сценарий назван вслух — значит, его можно оспорить. Человек, увидевший в первой реплике «иду разведкой, потому что способа не видно», поправит выбор одной фразой; молча выбранный сценарий он поправит через полчаса работы.