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

---
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/<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` в репозитории плагинов: правило
общее для всех, кто зовёт чужое, и ни один плагин им не владеет. Правится дом, а
не этот файл.

<!-- копия: граница-плагинов из 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: готовность записи<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](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`, не
  создавай веток, не пушь.
- Прогон проходит **один** чекпоинт, и это норма, а не упрощение. Два стопа за
  одну задачу — цена незнания способа, и платится она двумя прогонами, а не одним
  длинным.
- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси
  подтверждать механику: чекпоинт — единственное место, где ждут ответа.
- **Сценарий назван вслух — значит, его можно оспорить.** Человек, увидевший в
  первой реплике «иду разведкой, потому что способа не видно», поправит выбор
  одной фразой; молча выбранный сценарий он поправит через полчаса работы.