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

---
name: code-resolve
description: "Взять одну задачу и довести её до закрытия. Одна точка входа, три сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ известен и меняется поведение — сценарий решения: цикл Spec Driven Development (opsx propose → чекпоинт с объяснением человеческим языком, где форму решения одобряет человек → opsx apply → ревью кода постоянным составом → archive и отражение в документах молча → одна реплика о новом, где человек решает, что заводится: ADR, конвенция, задачи из урожая ревью → письмо одобренного → коммит → закрытие). Плановых стопов у сценария два, и оба про решения человека: чекпоинт до кода решает форму решения, реплика после кода — что из найденного переживёт задачу. Способ известен, а спека не меняется (тип chore: тулчейн, зависимости, сборка, гит-хуки, перенос, чистка) — сценарий обслуживания: правка → гейт со сверкой состава проверок → ревью фиксированным планом без change (autotests, operations, плюс conventions и техника, если тронут код) → синк документации, где почти всё письмо — отражение фактов и идёт молча → коммит → закрытие; планового стопа нет, change не заводится. Нашлась дельта-спека — задача оказалась шире своего типа: стоп с объяснением простым языком и двумя решениями человека, переформулировать запись в fix или feature и решать её процессом того типа следующим прогоном либо прекратить работу. Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → вычитка написанного → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст постановки: размеченная запись не обязательна — текст берётся так же, как его берёт opsx:propose, и текстом идут все три сценария. Использовать, когда просят взять, сделать или решить задачу — хоть записью из каталога, хоть описанием прямо в разговоре, — обновить зависимости или сборку, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога."
---

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

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

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

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

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

## Предпосылки

- **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка сценария решения**, а не
  опция. На них стоят его шаги 2, 4 и 6 и проход `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` берётся разведкой,
  если плагин есть.
- **Проектные копии этих скиллов и агентов удаляются при установке плагина.**

<!-- копия: проектные-копии из README.md -->

Голые имена в `.claude/skills/`: `resolve`, `review`, а у проектов прошлого
поколения ещё `task-pipeline`, `review-pipeline`, `task-batch`. С префиксом
проекта: `<проект>-task-pipeline`, `<проект>-review-pipeline`. Агенты:
`.claude/agents/<проект>-review-*.md`.

Две копии одного скилла расходятся, и побеждает та, что **короче названа**:
короткое имя разрешится в устаревшую проектную копию молча и без признаков
подмены.

<!-- /копия: проектные-копии -->

### Чего может не быть

**Копия.** Дом правила — `shared/absence.md` в репозитории плагина: правило
общее для всех, кто приходит в чужой проект, и ни один скилл им не владеет.
Правится дом, а не этот файл.

<!-- копия: отсутствие из av-dev/shared/absence.md -->

**Скилл не вправе считать раскладку проекта полной.** Части заводятся порознь и
живут порознь; каждая узнаётся своим следом:

| Чего нет | Как видно | Чего теперь не делает никто |
| --- | --- | --- |
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |

**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`,
`av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную
копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в
поведении.

**Внешний плагин может не стоять.** Их два: `opsx:*` — цикл SDD, и
`av-dev-git:commit` — сообщения коммитов. Путь в дерево чужого плагина не
пишется никогда: `$CLAUDE_PLUGIN_ROOT` ведёт только в своё дерево, а
вычисленный от него путь к соседу либо не откроется, либо откроет чужую
установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его
сам.

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

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

<!-- /копия: отсутствие -->

Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и `av-dev:task-track` —
все трое в этом же плагине и разрешаются всегда. Чем оборачивается отсутствие
части раскладки, под которую они работают, сказано на самих шагах сценариев.

Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё
не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта,
объёмы, модель угроз, прецеденты, — живут в **документах канона**;
карта «что где» — `references/project-facts.md` конвейера ревью.

**Документов канона нет — проект к нему не приведён.** Скажи это строкой и
предложи скилл `av-dev:canon`: одна операция на проект против поразрядной
деградации на каждой задаче. Работу при этом не останавливай.

## Вход

Задача задаётся **путём к файлу, именем файла, слагом или просто текстом**.
Ничего из этого не задано — попроси у вызывающего и остановись; сам в беклог не
лезь и приоритеты не интерпретируй: что делать дальше, решает не этот скилл.

**Форм постановки две, и обе полноправны:** запись каталога задач и текст,
переданный вызовом. Форма — не сценарий: развилка ниже у них общая, и текст
принимают все три сценария.

### Запись из каталога

**Запись сперва проверяется на готовность, и проверяет её машина.**
Вызови Skill `av-dev:task-track` и попроси прогнать `ready <слаг>`: он смотрит
тип, пустой ли раздел вопросов и собраны ли разделы схемы типа. Судить это глазами нельзя — ровно тот случай, где машина дешевле и точнее,
а цена ошибки отложенная: недостающие критерии приёмки обнаружатся на приёмке,
когда сверять уже не с чем.

**`ready` отказал — это исход, а не препятствие для тебя.** Скажи, чего не
хватает, и остановись: дописывать чужую запись за автора не твоя работа. Исход —
«не доведена», с названной причиной.

**Отказ `ready` сценарий не выбирает.** Запись `research` без раздела «Вопрос»
(сырьё) — отказ и здесь: у неё нет вопроса, и разведывать нечего.

Каталога задач в проекте нет — прогонять нечего, и постановка приходит текстом
по построению: дальше по разделу ниже.

### Постановка текстом

**Текст — вход, а не урезанный режим.** Ровно так берёт постановку
`opsx:propose`: предложение делается из фразы человека, а не из заранее
размеченной записи. Требовать записи там, где работа уместилась в разговор,
значит заводить учёт ради учёта — след у прогона остаётся и без неё: коммит, а у
решения ещё и заархивированный change.

**Первой репликой покажи, как ты понял постановку** — рядом с названным
сценарием, одной-двумя фразами: что считаешь предметом работы и где проводишь
границу. Запись толкуется по разделам, текст — молча, и расходится он с замыслом
ровно там, где его никто не показал. Человек, написавший текст, сидит в этом же
разговоре и поправляет одной фразой; автора записи, написанной месяц назад,
рядом нет, и потому текстовая постановка проверяется дешевле, а не хуже.

Что несёт запись и чем это заменяется, когда её нет:

| Что несёт запись | Чем заменяется у текста |
| --- | --- |
| готовность, проверенную машиной | читаешь постановку сам и говоришь строкой, что `ready` не гонялся |
| тип, объявленный автором | тип называешь ты — вслух, первой репликой, вместе со сценарием |
| критерии приёмки с оракулами | те, что есть в тексте; недостающие [решение](references/solve.md) добирает на чекпоинте, [обслуживание](references/maintain.md) объявляет строкой отсутствующими |
| адрес, куда ляжет ответ разведки | назначаешь сам и по канону, а не по удобству — [research.md](references/research.md), шаг 1 |
| закрытие как след работы | закрывать нечего, и шаг закрытия отпадает вместе с записью |

**Записи в каталог этот скилл не заводит — ни перед работой, ни задним числом
ради закрытия.** Граница «беклогом не владеет» действует и здесь. Работа не
уместилась в прогон, её надо ставить в очередь или из неё выросла пачка — скажи
это строкой и предложи `av-dev:task-track`: заводит он и по своим правилам.

**Похожую запись в беклоге не ищешь.** Человек назвал работу текстом — значит,
предмет прогона этот текст, а не строка индекса, которая на него похожа.
Наткнулся на такую строку по ходу — скажи о ней строкой доклада и не закрывай:
закрытие записи это приёмка, и поручали её не тебе.

## Развилка: какой сценарий

Сценарий — ось процесса; перечень осей и их границ —
[shared/axes.md](../../shared/axes.md).

Она в два вопроса, и оба стоят до всякой работы.

**Первый: есть ли у задачи один очевидный способ решения?**

- **нет** — тип `research`, сырая идея, новое и незнакомое, мутная постановка,
  два подхода с разной ценой. **Сценарий разведки** —
  [references/research.md](references/research.md);
- **есть** — что делать, понятно; спорно только как. Тогда второй вопрос.

**Второй: меняется ли то, что записано в `openspec/specs/`?**

- **меняется** — появляется или правится поведение. **Сценарий решения** —
  [references/solve.md](references/solve.md);
- **не меняется** — тулчейн и сборка, зависимости, гит-хуки и шаги гейта,
  перенос, чистка. **Сценарий обслуживания** —
  [references/maintain.md](references/maintain.md).

**Второй вопрос решается связкой из двух признаков, и оба обязательны:** тип
записи предлагает (`chore`, реже `fix`, возвращающий поведение к уже
записанному), а отсутствие дельт подтверждает. Тип объявляет автор и может
ошибиться; отсутствие дельт — твоё суждение и принимается только вместе с типом.
Признаки разошлись — это стоп, а не выбор: скажи, что тип и предмет работы не
сходятся, и остановись. Подробно — [maintain.md](references/maintain.md), раздел
«Признак — связка, а не одно условие».

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

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

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

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

- **решение → разведка**: обнаружилось, что очевидного способа нет. Это **стоп**
  с исходом «нужна разведка»: назови, что именно неясно, и не продолжай.
  Кода к этому моменту не написано, и писать его «пока разбираемся» нельзя;
- **обслуживание → решение**: нашлась дельта-спека, то есть поведение всё-таки
  меняется. Задача не сломалась — она **оказалась шире своего типа**, и стоп
  здесь несёт человеку выбор: назови тип, которым она оказалась (`fix` —
  расходится с заявленным, `feature` — снаружи появляется то, чего не было),
  объясни простым языком, что нашлось, и дай два решения — **переформулировать
  запись и решать процессом того типа следующим прогоном** либо **прекратить
  работу**. Третьего — «доделать как обслуживание» — нет. Исход в обоих случаях
  «меняется спека»; сделанное остаётся в рабочем дереве незакоммиченным, тип
  меняет `av-dev:task-track` и только после ответа. Подробно —
  [maintain.md](references/maintain.md), раздел «Дельта нашлась по ходу»;
- **обслуживание → разведка**: форма правки неизвестна (мажорное обновление,
  смена сборщика). **Стоп** с исходом «нужна разведка», по тому же основанию,
  что и у решения;
- **разведка → решение или обслуживание**: способ выбран на чекпоинте вариантов.
  Разведка **всё равно доводится до конца** — ответ записан, задачи уточнены,
  коммит сделан, — и работа идёт **следующим прогоном**, который запускает
  человек.

Обратной смены «решение → обслуживание» нет: задача, заведшая change, доводится
циклом решения. Дельта-спеки, оказавшиеся пустыми, — повод назвать это на
чекпоинте, а не свернуть на короткий путь из середины длинного.

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

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

    in --> form
    form -->|"запись каталога"| ready --> fork
    form -->|"текст"| plain --> fork
    fork -->|"да"| fork2
    fork -->|"нет"| res
    fork2 -->|"да"| solve
    fork2 -->|"нет: тип chore"| main
    solve -.->|"способа всё же нет:<br/>стоп, кода не написано"| res
    main -.->|"нашлась дельта: стоп,<br/>тип на fix или feature,<br/>следующим прогоном"| solve
    main -.->|"форма неизвестна:<br/>стоп"| res
    res -.->|"способ выбран:<br/>следующим прогоном,<br/>зовёт человек"| solve
```

Схема — **сводка**: содержание сценариев в их справочниках, и при расхождении
прав справочник.

## Кто пишет: письмо уходит агентам

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

Причина про контекст, и она одна. Оркестратор ведёт задачу целиком: выбрал
сценарий, собирает чекпоинт, сверяет перечень тем с исходом, пишет доклад, — а
для всего этого надо помнить постановку, критерии приёмки и то, что человек
одобрил. Письмо тянет в контекст ровно то, чего в докладе не будет ни строкой:
содержимое тронутых файлов, вывод линтеров и гейта, перебранные варианты правки.
Забитый этим контекст теряет одобренное и постановку — и теряет **молча**: доклад
остаётся связным, а сверять его уже не с чем.

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

| Работа | Где шаг |
| --- | --- |
| предложение и дельта-спеки — `opsx:propose` | [solve](references/solve.md), шаг 2 |
| правки спек и дизайна по сказанному на чекпоинте | [solve](references/solve.md), шаг 3 |
| код — `opsx:apply`, вместе с гейтом до зелёного и поведенческой верификацией | [solve](references/solve.md), шаг 4 |
| правки по находкам триажа, помеченным `инлайн` | [solve](references/solve.md), шаг 5; [maintain](references/maintain.md), шаг 4 |
| правка оснастки в сценарии обслуживания | [maintain](references/maintain.md), шаг 2 |
| архивация change и отражение в документах — `opsx:archive` и `av-dev:doc-sync` | [solve](references/solve.md), шаг 6, такт 1; [maintain](references/maintain.md), шаг 5 |
| письмо одобренного нового и задачи из урожая | [solve](references/solve.md), шаг 6, такт 3 |

**Остальное остаётся оркестратору, и перечень закрыт:** выбор сценария и стопы,
чекпоинт, вызовы `av-dev:code-review`, `av-dev-git:commit` и `av-dev:task-track`,
сверка плана с исходом, урожай и доклад. **Коммит и закрытие задачи агенту не
отдаются ни в одном сценарии** — они необратимы для учёта: закрытие удаляет запись
и правит индексы, а коммит уезжает в историю. Оркестратор делает их сам, уже
сверив перечень тем с исходом. Ни одна из этих
работ не пишет файлов проекта — они и есть та работа, ради которой контекст
берегут.

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

### Устава у этих агентов нет

Проходы ревью ходят уставами (`av-dev/agents/`), потому что уставом задаётся
**суждение**: что искать и что считать находкой. Здесь суждения нет — работа
нормирована скиллами `opsx:*`, конвенциями проекта и находками триажа, а устав
стал бы вторым домом того же и разошёлся бы с ним молча. Зовётся агент общего
назначения, и всё, чем один его прогон отличается от другого, приходит заданием.

### Задание собирается адресами

**Агент не видел разговора.** Он не знает ни постановки, ни выбранного сценария,
ни того, что уже одобрено на чекпоинте. Поэтому задание самодостаточно, а вещи в
нём называются **адресами, а не пересказом** — по тому же правилу, по которому
проход ревью получает дом темы путём и разделом. В задании:

- корень проекта, текущая ветка и база диффа. Ветку агент не создаёт и не
  переключает, не пушит — правило то же, что у скилла;
- **что делать**: файл задачи либо её текст дословно, критерии приёмки,
  идентификатор change;
- **что читать**: `CLAUDE.md`, конвенции проекта, дельта-спеки change;
- **находки — дословно**, как их вернул триаж, вместе с
  оракулом;
- **границы**: правится названное, соседнее не улучшается заодно; развилок агент
  не решает, задач не заводит, ничего не коммитит и наружу не ходит — правило
  необратимого действует и на него (раздел «Когда спрашивать вне чекпоинта»);
- **чем кончает**: гейт зелёный, а если задача меняет наблюдаемое поведение —
  прогнана поведенческая верификация.

**Пересказ находки — самая дорогая экономия из возможных.** Находка триажа несёт
оракул, и пересказ теряет как раз его: агент чинит то, что понял, гейт зеленеет,
а в отчёт уезжает «исправлено».

### Возврат — не длиннее экрана

Агент возвращает: что сделано, **адресами** тронутого; исход гейта, чем он
прогнан, где логи шагов и **отпечаток дерева сразу после прогона**; что не
удалось и почему; вопросы, если по заданию их не разрешить. Отпечаток нужен
ревью: по нему ступень автотестов засчитывает этот прогон вместо своего
(`av-dev:code-review`, ступень 1) — без него гейт гоняется дважды на том же
дереве.
Диффа, пересказа кода и логов в возврате нет — иначе экономия, ради которой шаг
и вынесен, отменяется в момент возврата.

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

**Предложения из этого чек-листа оркестратор не исполняет сам.** Они уезжают в
реплику человеку вместе с урожаем ревью, и написанным становится только то, что
он назвал (`solve.md`, шаг 6, такт второй). Агент, вернувший предложение, свою
работу сделал — заведение нового не его решение и не твоё.

**Возврату на слово не верят, и перечитывать за агентом дифф для этого не надо.**
Верят независимым артефактам: зелёному гейту, отчёту триажа, ревью следующего
шага. Своей прозе здесь верить нельзя ровно по той причине, по которой ей не
верит конвейер ревью, — её написал тот, кто мог и пропустить.

**Артефакты, написанные для человека, оркестратор читает сам**: `proposal.md` и
`design.md` нужны ему на чекпоинте. Это не переполнение контекста, а его работа.

### Один агент на шаг, а не на файл

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

**Правило про контекст, а не про полномочия.** Агент упал, вернул не то или не
понял задания — повтори задание, дописав то, чего в нём не хватило. Не вышло и во
второй раз — делай сам и **скажи это строкой доклада**: прогон стоил дороже, чем
должен, и это факт для человека, а не стоп.

## Автономность и плановый стоп

**У двух сценариев ровно один плановый стоп**, и стоят они в разных местах:
у решения — объяснение сразу после предложения и до кода, у разведки — варианты
до первого написанного требования. Правило вокруг них общее.

**У обслуживания планового стопа нет вовсе, и это следствие, а не поблажка.**
Один стоп с ожиданием ответа у него всё же есть — по найденной дельта-спеке, — но
плановым он не является: через него проходят только те прогоны, где задача
оказалась не тем, чем объявлена.
Чекпоинт объясняет человеку **выбор**, а у обслуживания выбора нет по
построению: что делать, сказано в записи, и объяснение свелось бы к пересказу
задачи её же автору. Стоп, на котором нечего решать, вырождается в обряд
одобрения и обесценивает те стопы, где решать есть что. Правило необратимого
(ниже) действует там полностью и срабатывает чаще, чем в двух других сценариях:
выкладка, токены, хуки и чужие данные — обычное содержимое задач обслуживания.

**Вокруг чекпоинта умолчание прежнее — делать, а не спрашивать.** Чекпоинт не
отменяет автономность, он даёт развилкам плановое место, куда копиться.

Разрез простой:

- развилка найдена **до** чекпоинта — она его и ждёт. Не спрашивай отдельно:
  чекпоинт рядом и стоит дёшево, а три вопроса подряд стоят дороже одного
  разговора;
- развилка найдена **после** чекпоинта — старое правило: **запиши вопрос и доведи
  остаток**, не останавливаясь.

Запись вопроса устроена так:

1. **Запиши там, где проект держит вопросы** (секция беклога, файл задачи,
   трекер — это знает проект). Проект не сказал, куда, — отдельной секцией
   `Вопросы` в своём докладе, и это тоже исход. Тело отвечает на три вещи: **что
   именно решить**, **какие есть варианты и цена каждого**, **что стоит, пока
   решения нет**. Плюс твоя рекомендация — человек чаще соглашается, чем выбирает
   заново, и готовое суждение экономит ему весь контекст.
2. **Переформулируй задачу на остаток** — то, что делается без этого решения.
   Назови границу: докуда доводим сейчас.
3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана
   в объявленных границах. В разведке остаток — это ответ в объявленных рамках:
   что успели узнать, где остановились и почему.

**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими
оговорками — в скилле `av-dev:task-groom`, раздел
`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания».
Правило принадлежит управлению задачами, потому что решает **сделана задача или
вышла**, — это исход планирования, а не исполнения. **Ссылайся, не
пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и
потеряла из перечня самое необратимое — запись **наружу**.

Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами —
**материализация нерешённого** (запись состояния, зависящего от неотвеченного
вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке).
Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход
«не доведена».

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

Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос
записан, ничего не коммитится наполовину.

### Когда спрашивать вне чекпоинта

По другому основанию — не «сложное решение», а **необратимое действие**:

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

Здесь ошибка не откатывается коммитом, поэтому спрашиваем даже когда решение
кажется очевидным.

## Границы: чем этот скилл не владеет

- **Беклогом и порядком работ.** Задача приходит извне. Скилл её не выбирает,
  не переставляет, не заводит и не переоценивает.
- **Форматом задач и документов.** Индексы и документы канона руками не правятся,
  путь к чужому скрипту не выдумывается: этим владеют `av-dev:task-track` и
  `av-dev:doc-sync`. Закрытие — работа этого скилла, и это осознанное решение с
  названной ценой: **приёмщик и исполнитель совпали**. Закрытие поэтому **не окончательно** — человек
  возвращает задачу `reopen` с причиной (на доработке это делают грумингом,
  `av-dev:task-groom`, на стройке — сразу, как заметили), а доклад
  по критериям приёмки становится единственным, по чему приёмка вообще возможна.
- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос этого
  скилла ни на одном шаге и ни в одном сценарии. Чекпоинт решения спрашивает «так
  ли решаем», чекпоинт разведки — «каким из способов», но не «надо ли».

Что не принадлежит **отдельному сценарию**, названо у него же: урожай ревью и
выбор способа — в [solve.md](references/solve.md), изменение поведения и нарезка
пачки — в [maintain.md](references/maintain.md), код и приоритет — в
[research.md](references/research.md).

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

**У каждого сценария их четыре**, и живут они у сценария:
[решение](references/solve.md) — сделана, не доведена, оказалась крупнее задачи,
нужна разведка; [обслуживание](references/maintain.md) — сделана, не доведена,
меняется спека, нужна разведка; [разведка](references/research.md) — способ
выбран, знание записано, отказ, не доведена.

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

## Доклад

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

- **какой сценарий шёл** — решение, обслуживание или разведка, — и почему выбран
  он;
- **исход** одним из четырёх слов своего сценария и, если он не благополучный,
  чем ограничен результат;
- **постановка пришла текстом** — сказать это прямо: как она понята, что `ready`
  не гонялся и что закрывать было нечего;
- что сделано, какие вопросы записаны и куда;
- **шаг письма, сделанный не агентом, а тобой** — с причиной: раздел «Кто пишет»
  требует называть это строкой, а не молча;
- чего проверить или узнать **не удалось**.

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

## Тонкости

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