dev-skills/av-dev/skills/code-resolve/references/research.md

Сценарий «разведка»

Отвечает на вопрос задачи и записывает ответ туда, где он переживёт переписку. Исход — знание: уточнённые документы и уточнённые задачи. Кода этот сценарий не пишет и change не заводит.

Сценарий выбирается развилкой на входе скилла (SKILL.md, раздел «Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его ход; общее для всех трёх сценариев — вход, чего может не быть, правило необратимого, доклад — живёт в SKILL.md и тут не пересказывается.

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

OpenSpec здесь не предпосылка

OpenSpec этому сценарию не нужен, и это единственное место скилла, где он не предпосылка. Разведка не заводит change и не пишет дельта-спеки: её артефакты — документы канона и записи каталога задач. Скилл opsx:explore полезен и зовётся, когда внешний плагин установлен; не разрешился — разведка идёт чтением документов, кода и внешних источников, и это говорится строкой доклада, а не отменяет работу.

Кого зовёт этот сценарий

av-dev:doc-sync (ответ уезжает в документы канона), av-dev:task-track (задачи заводятся и уточняются), av-dev-git:commit. Правило обращения к соседям и правило «чего может не быть» — общие, они в SKILL.md.

Агентов-исполнителей у разведки нет (SKILL.md, «Кто пишет: письмо уходит агентам»), и это не пропуск. Её письмо — записка в документы канона и записи задач, то есть тот самый текст, из которого собираются чекпоинт вариантов и доклад: отданный агенту, он вернулся бы пересказом. Вычитку разведка всё же отдаёт — doc-wording, task-form, task-wording: там судят написанное, а не пишут.

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

Что этот сценарий требует от входа

Вход общий у всех трёх сценариев (SKILL.md, раздел «Вход»); своего здесь три условия.

Паспорт читается раньше кода. Граница домена и «чем проект не является» отсекают половину вариантов до того, как их начнут сравнивать, — а сравнение вариантов и есть работа этого сценария.

Сырьё — research без раздела «Вопрос» — не берётся. Исход «не доведена» с причиной «запись это сырьё»: у неё нет вопроса, а разведка без вопроса превращается в чтение всего подряд с отчётом «интересно, но неприменимо». Дописывать вопрос за автора не твоя работа — этим занят штурм сырья в av-dev:task-track. Назови, чего не хватает, и остановись.

Разведка пришла текстом — сформулируй вопрос сам одной фразой и покажи формулировку в первой же реплике. Разведка, чей вопрос не назван вслух, признаётся удавшейся любым результатом. Это частный случай общего правила (SKILL.md, «Постановка текстом»): у разведки показать надо не только предмет работы, но и сам вопрос, потому что предмет разведки — он и есть. Вместе с вопросом называются рамки и адрес ответа (шаг 1).

Ход работы

flowchart TD
    in["вход: файл, слаг или текст"]
    s1["1. вопрос и рамки<br/>сырьё без «Вопроса» — отказ"]
    s2["2. разведка: документы, код,<br/>внешние источники, opsx:explore"]
    s3(["3. ЧЕКПОИНТ: варианты<br/>2–4 способа, цена каждого,<br/>что становится невозможным"])
    s4["4. ответ в документы канона<br/>av-dev:doc-sync"]
    s5["5. задачи: завести и уточнить<br/>av-dev:task-track"]
    s6["6. вычитка написанного:<br/>документы и записи задач"]
    s7["7. гейт проекта, затем коммит<br/>av-dev-git:commit"]
    s8["8. закрыть разведку — av-dev:task-track,<br/>вторым коммитом учёта"]
    out["исход назван: знание, задачи,<br/>отказ или «не доведена»"]

    in --> s1 --> s2 --> s3
    s3 -->|"выбран способ,<br/>отказ или знание"| s4
    s3 -.->|"вопрос не тот"| s1
    s4 --> s5 --> s6 --> s7 --> s8 --> out

Схема — сводка: содержание каждого шага в его разделе ниже, и при расхождении прав текст.

Плановый стоп сценария

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

Стоп здесь один, и стоит он перед записью. Причина в цене: пока варианты живут в контексте, смена решения стоит абзаца; записанный в документы и разложенный на задачи выбор стоит правки документов и разбора беклога. Второго стопа — «покажи, что именно уедет в документы» — нет намеренно: всё, что пишет разведка, лежит в git и читается диффом, а второй стоп на каждой разведке вырождается в ритуал одобрения.

Правило необратимого действует и здесь (SKILL.md, «Когда спрашивать вне чекпоинта»), и разведка обманчива: она кажется безобидной, а замер лезет туда, где живут данные — прогон на боевой базе, запрос к внешнему платному источнику. Здесь ошибка не откатывается правкой текста.

Границы: чего разведка не делает

• Кодом. Ни строки, включая «маленький черновик, чтобы проверить». Замер, требующий кода, — это отдельная задача, и её нужно назвать, а не написать по ходу. Исключение ровно одно и оно не про изменение системы: одноразовый читающий прогон (запрос, замер, скрипт в песочнице), чей результат уезжает в ответ с происхождением и который ничего не оставляет в репозитории.
• Местом в списке. Заведённая задача встаёт в конец своей секции; куда её поставить, решает человек — на доработке грумингом (av-dev:task-groom), на стройке сразу же, по зависимости. Разведка, сама ставящая свой исход первым, назначает место тому, что только что придумала.
• Форматом задач и документов. Индексы и документы руками не правятся: их ведут av-dev:task-track и av-dev:doc-sync. Твоё — содержание ответа, их — форма и дом.
• Определением ценности. «Нужно ли это делать вообще» — вопрос человека. Разведка отвечает «как это можно сделать и чего каждый способ стоит».
• Решением задачи. Выбранный способ реализует сценарий решения, и запускает его человек следующим прогоном. Перейти в него по ходу нельзя — это тот самый переход, ради невозможности которого сценарии и разведены.

Наблюдаемые исходы сценария

Четыре, и каждый обязан быть назван в докладе прямо. Первые три — это те самые «заведены задачи, записано знание, отказ», которыми кончается разведка по определению типа research:

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

Определение сделанного для разведки

У сценария решения оно своё (SKILL.md); здесь — короткое и другое. Разведка сделана, когда верно всё:

1. ответ записан по адресу, который назвала задача — раздел «Куда ляжет ответ». Адреса не было, а вопрос был — ты назначил адрес сам и сказал об этом строкой;
2. у каждого числа названо происхождение — команда или условия, которыми оно получено. Число без источника проход ревью обязан читать как условие, а не как замер, и разведка, оставившая голые числа, вредна: по ним будут решать;
3. отвергнутые варианты названы с причиной. Отвергнутое без причины возвращается на следующей разведке как новая идея;
4. задачи, которые исход породил, заведены — или явно сказано, что не породил;
5. написанное вычитано — документы агентом doc-wording, записи задач проходами task-form и task-wording, каждый по своей пачке;
6. написанное закоммичено, разведка закрыта.

Шаги

1. Вопрос и рамки

Прочитай запись. У типа research два обязательных раздела, и оба нужны тебе прямо сейчас: «Вопрос» — на что отвечаем, «Куда ляжет ответ» — по какому адресу он ляжет. Адрес назван заранее не из аккуратности: ответ, не имеющий дома, остаётся в переписке, и через квартал разведку заказывают заново.

Адрес назначает автор записи, а не ты. Запись из каталога без него до тебя не доходит: ready требует непустыми оба раздела и откажет — это стоп со строкой, чего не хватает, а не повод дописать за автора. Иначе исполнитель сам назначает себе приёмку, а приёмка разведки — это и есть записанный по названному адресу ответ.

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

Что узнали	Дом ответа
наблюдение о внешнем мире, замер с происхождением	docs/research/
решение с ценой: намеренный отказ, дорогой откат	docs/adr/
факт об устройстве системы	тема architecture (или своя тема проекта)
граница домена, «чем проект не является»	passport
ответ нужен только этой работе	тело самой записи

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

Здесь же проверка на «не тот вопрос»: если из записи видно, что отвечать надо на другое, скажи это сразу, а не после разведки.

2. Разведка

Порядок чтения — от дешёвого к дорогому, и он не произволен:

1. документы канона проекта — половина вопросов уже отвечена там, и разведка, начатая с кода, переоткрывает написанное;
2. код и его история — git log по узлу отвечает на «почему так» чаще, чем кажется;
3. внешние источники — документация формата, чужой опыт, спецификации;
4. замер — если вопрос про числа. Числа снимаются с происхождением, иначе они бесполезны на следующем шаге.

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

Развилку разведки не записывай вопросом — она и есть предмет следующего шага.

3. Чекпоинт: варианты

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

Форма — короткая, экран текста:

• вопрос, на который отвечаем, одной фразой (он уже есть в записи);
• 2–4 варианта, не больше. Больше четырёх — это не выбор, а список: человек не сравнит, а признает свою неспособность сравнить и попросит рекомендацию. У каждого варианта: в чём суть простыми словами, что даёт, чего стоит, что становится невозможным (это ловится хуже всего и стоит дороже всего);
• рекомендация с причиной. Человек чаще соглашается, чем выбирает заново;
• что известно недостоверно и как это проверить, если проверять дёшево;
• что уедет в документы и в задачи, если возражений нет, — одной строкой. Это не второй стоп, а предупреждение: человек видит объём последствий там же, где принимает решение.

Что нельзя: приносить варианты, различающиеся только реализацией; прятать отвергнутое (отвергнутый вариант с названной причиной — половина будущего ADR); приносить один вариант и называть это выбором.

Проверка на простой язык — общая у трёх сценариев:

в тексте нет SHALL, нет имён файлов и функций там, где вещь называется по-русски, и нет слов, которых нет в паспорте проекта.

Исходы чекпоинта:

• выбран способ — идёшь на шаг 4, исход разведки будет «способ выбран». Кода ты по нему не пишешь: сценарий кончается записью и коммитом;
• ответ и есть результат — идёшь на шаг 4, исход «знание записано» или «отказ»;
• вопрос не тот — возвращаешься на шаг 1: переформулируй вопрос и скажи, что из разведанного остаётся в силе;
• ни один вариант не одобрен — исход «не доведена» с причиной. Записывается всё равно то, что узнано (шаг 4): выброшенная разведка будет заказана заново.

4. Ответ в документы канона

Вызови Skill av-dev:doc-sync: он владеет содержимым документов канона. Передай ему ответ, адрес из шага 1 и происхождение каждого числа — писать содержание за тебя он не будет, но дом и форму держит он. Вычитка языка — тоже его агент, но момент её назван отдельно, шагом 6: пачка собирается из шагов 4 и 5 и до конца пятого не полна.

Что именно уезжает:

• ответ на вопрос — по адресу из шага 1;
• отвергнутые варианты с причинами. Это половина будущего ADR и единственная защита от повторной разведки того же самого;
• решение с ценой — в ADR, если оно проходит триггер канона. У разведки, кончившейся без кода, design.md не будет никогда, поэтому здесь ADR цитирует записку разведки, а не архивный change; канон это допускает прямо, и в записи источник называется.

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

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

Документов канона в проекте нет — писать ответ некуда: назови это исходом, предложи завести канон скиллом av-dev:canon и оставь ответ в докладе целиком, чтобы работа не пропала. Заводить docs/ мимо канона нельзя.

5. Задачи: завести и уточнить

Вызови Skill av-dev:task-track. Он владеет форматом, дедупом и индексами; путь к его скрипту не выясняй и индексы руками не правь.

Что просишь сделать:

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

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

Каталога задач в проекте нет — задачи остаются списком формулировок в докладе, и это говорится строкой: учёт работ остаётся за владельцем.

6. Вычитка написанного — до гейта, не после

Разведка правит две вещи сразу: документы канона (шаг 4) и записи каталога задач (шаг 5). Обе — текст, и портится он в момент письма, а машина этого не видит: docs.py check и tasks.py check смотрят форму раскладки, а не залог, оценку без факта, жаргон и термин, которого нет в паспорте проекта.

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

• Документы — агент doc-wording, владеет им av-dev:doc-sync (раздел «Вычитка»). Пачка — адреса, названные на шаге 4, включая docs/adr/ и docs/research/.
• Записи задач — два прохода, сперва task-form, затем task-wording; владеет ими av-dev:task-track (раздел «Вычитка: два прохода»). Пачка — заведённые и уточнённые на шаге 5 записи. Заголовок и «зачем» правятся не молча: покажи предложенное вместе с тем, что было.

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

Судей канона — doc-consistency и doc-code-drift — здесь не зови. Они идут на весь канон разом, стоят дорого, и владеет ими av-dev:doc-healthcheck, момент вызова которого выбирает человек. Нужно суждение о согласованности — скажи строкой и предложи healthcheck, а не зови агентов сам.

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

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

7. Гейт и коммит

Сперва гейт проекта — тот же, что гоняет сценарий решения, и по той же причине: разведка только что правила документы канона и индексы задач, а это ровно то, что машина умеет проверить (docs.py check, tasks.py check --dir, битые ссылки). Красный гейт чинится здесь, а не оставляется следующему прогону: он придёт за код и получит чужую поломку в наследство.

Гейта в проекте нет — скажи строкой, что записанное не проверял никто.

Коммить в текущую ветку (git rev-parse --abbrev-ref HEAD), сам ветку не создавай и не переключай, ничего не пушь.

Сообщение — по-русски, скиллом av-dev-git:commit: форму сообщения держит он, и здесь она не пересказывается. Вызов не разрешился — напиши сообщение сам и скажи строкой, что форму коммита не сверял никто.

Одна разведка — один осмысленный коммит: записанный ответ и заведённые задачи уезжают вместе, потому что порознь они полуправда.

8. Закрыть разведку — после коммита, не раньше

Вызови Skill av-dev:task-track и попроси закрыть запись: ответ записан — close --implemented, ушла без ответа — close --reason, и строка уезжает в кладбище.

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

Закрытие тоже коммитится — вторым коммитом, тут же. Сообщение короткое, про учёт, а не про работу: закрыта задача <slug>. Правило «одна разведка — один коммит» про работу, а учёт — не работа.

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

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

Доклад разведки

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

• исход одним из четырёх слов;
• вопрос и ответ — по фразе на каждое. Ответ, который не сворачивается во фразу, — признак того, что разведка отвечала не на один вопрос;
• куда записано — перечнем адресов, а не «документация обновлена»;
• какие задачи заведены и уточнены — слагами;
• что вычитано и чем — пачка документов и пачка записей, каждая со своими проходами; не вычитанное называется прямо, вместе с причиной;
• сигнал сверки — строка синка о том, сколько задач сделано с прошлого прогона av-dev:doc-healthcheck, либо что сверки не было ни разу;
• что осталось неизвестным и чего это стоит: разведка без этой строки сообщает «выяснено», не сообщая, что именно осталось не выяснено;
• рамки, если они ограничили работу: докуда копали и почему остановились.

Тонкости

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