diff --git a/DECISIONS.md b/DECISIONS.md index e6f75b6..3be8471 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3779,3 +3779,44 @@ change по нему не будет никогда, — и такое реше 208. **Работа без своего исхода вырождается в пролог.** Разведка, кончавшаяся переходом к коду, не имела причины писать в документы: её ответ и так уезжал в `design.md`. Дом для исхода — вот что делает работу работой. + +## 62. Вычитку зовёт тот, кто правил, а не тот, кто синкал (2026-08-11) + +Вычитка документов агентом `doc-wording` была привязана к **синку**: «позови его +последним шагом синка», «ничего не правивший синк агента не зовёт». Сценарий +разведки о себе говорит обратное — «правило принуждённого отрицания здесь не +действует, это не синк», — и при буквальном чтении вычитка не доставалась ему +вовсе: документы правились, а звать было некому. Гейт перед коммитом машинный, он +смотрит раскладку и битые ссылки, а не залог и неизвестный термин. + +**Условие вызова теперь — правка, а не обряд, внутри которого она случилась.** +Признак читается буквально: документы правились — зови, ничего не правил — не +зови. Синк остался самым частым вызывающим, но перестал быть единственным. + +**У разведки вычитка стала своим шагом, а не оговоркой внутри чужого.** Она стоит +между записью и гейтом, потому что раньше пачка не полна: разведка правит две +вещи сразу — документы канона и записи каталога задач, — и собирается пачка +только к концу пятого шага. После коммита вычитка правила бы уже закоммиченное. + +**Обе пачки судятся своими проходами.** Документы — `doc-wording`, записи задач — +`task-form`, затем `task-wording`; владеет каждым проходом его плагин, и разведка +их не зовёт напрямую, а просит владеющий скилл. + +**Запрет остался, но только на судей канона.** `doc-consistency` и +`doc-code-drift` идут на весь канон разом и стоят дорого — их момент выбирает +человек через `av-dev-docs:healthcheck`. Смешение этого запрета с вычиткой и было +второй половиной поломки: «агентов по документам на отдельной работе не зовут» +читалось как правило про всех троих. + +### Что из этого следует + +209. **Правило, привязанное к названию обряда, не срабатывает у того, кто себя + этим обрядом не считает.** Условие вызова формулируется через наблюдаемое + действие — «правил текст», — а не через имя фазы, внутри которой оно обычно + происходит. +210. **Дорогая проверка и дешёвая проверка не живут под одним запретом.** Довод + «не зови агентов сам» верен для судей на весь канон и обратен для вычитки + названной пачки; общая формулировка отменяет вторую вместе с первой. +211. **Шаг, собирающий пачку, стоит после последнего, кто в неё кладёт.** Вычитка + на шаге записи проверила бы половину написанного, а после коммита — уже + историю. diff --git a/README.md b/README.md index 0c94118..0b02629 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,9 @@ **Разведка** (тип `research`, сырая идея, мутная постановка) кода не пишет вовсе: её чекпоинт — варианты, 2–4 способа решить с ценой каждого, — стоит до первого написанного требования, а исход уезжает в документы канона и в - задачи. Выбранный способ реализуется **следующим прогоном**, и запускает его + задачи. Обе пачки — документы и записи — **вычитываются перед коммитом** + своими проходами: `doc-wording` по документам, `task-form` и `task-wording` + по записям. Выбранный способ реализуется **следующим прогоном**, и запускает его человек: смена сценария по ходу — событие с названным исходом, а не тихий поворот. Оба сценария лежат справочниками и одинаково — `references/solve.md` и `references/research.md`; в самом скилле только вход, развилка и правила, diff --git a/av-dev-code/skills/resolve/SKILL.md b/av-dev-code/skills/resolve/SKILL.md index 98fe8d4..1621fe1 100644 --- a/av-dev-code/skills/resolve/SKILL.md +++ b/av-dev-code/skills/resolve/SKILL.md @@ -1,6 +1,6 @@ --- name: resolve -description: "Взять одну задачу и довести её до закрытия. Одна точка входа, два сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ решения известен — сценарий решения: цикл Spec Driven Development (opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие). Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст. Использовать, когда просят взять, сделать или решить задачу, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога." +description: "Взять одну задачу и довести её до закрытия. Одна точка входа, два сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ решения известен — сценарий решения: цикл Spec Driven Development (opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие). Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → вычитка написанного → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст. Использовать, когда просят взять, сделать или решить задачу, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога." --- # Работа над одной задачей diff --git a/av-dev-code/skills/resolve/references/research.md b/av-dev-code/skills/resolve/references/research.md index f0cd301..9d21797 100644 --- a/av-dev-code/skills/resolve/references/research.md +++ b/av-dev-code/skills/resolve/references/research.md @@ -63,14 +63,15 @@ flowchart TD s3(["3. ЧЕКПОИНТ: варианты
2–4 способа, цена каждого,
что становится невозможным"]) s4["4. ответ в документы канона
av-dev-docs:docs"] s5["5. задачи: завести и уточнить
av-dev-tasks:tasks"] - s6["6. гейт проекта, затем коммит
av-dev-git:commit"] - s7["7. закрыть разведку — av-dev-tasks:tasks,
вторым коммитом учёта"] + s6["6. вычитка написанного:
документы и записи задач"] + s7["7. гейт проекта, затем коммит
av-dev-git:commit"] + s8["8. закрыть разведку — av-dev-tasks:tasks,
вторым коммитом учёта"] out["исход назван: знание, задачи,
отказ или «не доведена»"] in --> s1 --> s2 --> s3 s3 -->|"выбран способ,
отказ или знание"| s4 s3 -.->|"вопрос не тот"| s1 - s4 --> s5 --> s6 --> s7 --> out + s4 --> s5 --> s6 --> s7 --> s8 --> out ``` Схема — **сводка**: содержание каждого шага в его разделе ниже, и при расхождении @@ -146,7 +147,9 @@ git и читается диффом, а второй стоп на каждой 3. **отвергнутые варианты названы с причиной**. Отвергнутое без причины возвращается на следующей разведке как новая идея; 4. задачи, которые исход породил, заведены — или явно сказано, что не породил; -5. написанное закоммичено, разведка закрыта. +5. **написанное вычитано** — документы агентом `doc-wording`, записи задач + проходами `task-form` и `task-wording`, каждый по своей пачке; +6. написанное закоммичено, разведка закрыта. ## Шаги @@ -242,7 +245,9 @@ git и читается диффом, а второй стоп на каждой **Вызови Skill `av-dev-docs:docs`**: он владеет содержимым документов канона. Передай ему ответ, адрес из шага 1 и провенанс каждого числа — писать содержание -за тебя он не будет, но дом, форму и вычитку держит он. +за тебя он не будет, но дом и форму держит он. Вычитка языка — тоже его агент, но +момент её назван отдельно, шагом 6: пачка собирается из шагов 4 и 5 и до конца +пятого не полна. **Что именно уезжает:** @@ -290,7 +295,41 @@ git и читается диффом, а второй стоп на каждой Плагина нет — задачи остаются **списком формулировок в докладе**, и это говорится строкой: учёт работ остаётся за владельцем. -### 6. Гейт и коммит +### 6. Вычитка написанного — до гейта, не после + +Разведка правит **две вещи сразу**: документы канона (шаг 4) и записи каталога +задач (шаг 5). Обе — текст, и портится он в момент письма, а машина этого не +видит: `docs.py check` и `tasks.py check` смотрят форму раскладки, а не залог, +оценку без факта, жаргон и термин, которого нет в паспорте проекта. + +Пачка **собирается только сейчас**, и поэтому шаг стоит здесь: раньше пятого шага +она не полна, а после коммита вычитка уже правит закоммиченное. + +- **Документы** — агент `doc-wording`, владеет им `av-dev-docs:docs` (раздел + «Вычитка»). Пачка — адреса, названные на шаге 4, включая `docs/adr/` и + `docs/research/`. +- **Записи задач** — два прохода, сперва `task-form`, затем `task-wording`; + владеет ими `av-dev-tasks:tasks` (раздел «Вычитка: два прохода»). Пачка — + заведённые и уточнённые на шаге 5 записи. Заголовок и «зачем» правятся **не + молча**: покажи предложенное вместе с тем, что было. + +**Что не правилось, то не вычитывается.** Разведка, кончившаяся одним документом +и ни одной задачей, зовёт один проход, и это не пропуск — это названная строкой +пачка. Скилл-владелец уже прогнал свою пачку по ходу шага — назови это и второй +раз тот же файл не гоняй. + +**Судей канона — `doc-consistency` и `doc-code-drift` — здесь не зови.** Они +идут на весь канон разом, стоят дорого, и владеет ими `av-dev-docs:healthcheck`, +момент вызова которого выбирает человек. Нужно суждение о согласованности — скажи +строкой и предложи `healthcheck`, а не зови агентов сам. + +Ни один проход ничего не правит: они возвращают готовые формулировки, +подставляешь их ты — и уже с подставленными идёшь на гейт. + +Плагина нет — вызов не разрешится: скажи строкой, что написанное не вычитывал +никто, и обходного пути не выдумывай. + +### 7. Гейт и коммит **Сперва гейт проекта** — тот же, что гоняет сценарий решения, и по той же причине: разведка только что правила документы канона и индексы задач, а это @@ -310,14 +349,14 @@ git и читается диффом, а второй стоп на каждой Одна разведка — один осмысленный коммит: записанный ответ и заведённые задачи уезжают вместе, потому что порознь они полуправда. -### 7. Закрыть разведку — после коммита, не раньше +### 8. Закрыть разведку — после коммита, не раньше **Вызови Skill `av-dev-tasks:tasks`** и попроси закрыть запись: ответ записан — `close --implemented`, ушла без ответа — `close --reason`, и строка уезжает в кладбище. **Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно -оставило бы разведку закрытой без единого следа работы, если шаг 6 упадёт. У +оставило бы разведку закрытой без единого следа работы, если шаг 7 упадёт. У разведки это опаснее, чем у решения: следом работы там служит код, а здесь — только записанный ответ. Закрытая разведка без него не оставляет следа вообще — файл задачи удалён, ответ был в переписке. @@ -340,6 +379,8 @@ git и читается диффом, а второй стоп на каждой фразу, — признак того, что разведка отвечала не на один вопрос; - **куда записано** — перечнем адресов, а не «документация обновлена»; - **какие задачи заведены и уточнены** — слагами; +- **что вычитано и чем** — пачка документов и пачка записей, каждая со своими + проходами; не вычитанное называется прямо, вместе с причиной; - **что осталось неизвестным** и чего это стоит: разведка без этой строки сообщает «выяснено», не сообщая, что именно осталось не выяснено; - **рамки**, если они ограничили работу: докуда копали и почему остановились. diff --git a/av-dev-docs/skills/docs/SKILL.md b/av-dev-docs/skills/docs/SKILL.md index 073eccd..78572f0 100644 --- a/av-dev-docs/skills/docs/SKILL.md +++ b/av-dev-docs/skills/docs/SKILL.md @@ -77,16 +77,21 @@ description: Вести содержимое документов канона ## Вычитка — наоборот, здесь -**Язык правленого вычитывается на синке, и зовёшь агента `doc-wording` ты.** -Довод обратный доводу про судей: он читает **только названную пачку**, стоит -дёшево и ищет ровно то, что портится в момент письма, — залог, оценку без факта, -жаргон, термин без ввода. Ждать `healthcheck` здесь нечего: через месяц никто уже -не помнит, какую фразу имел в виду автор. +**Язык правленого вычитывается тем же прогоном, который его написал, и зовёшь +агента `doc-wording` ты.** Довод обратный доводу про судей: он читает **только +названную пачку**, стоит дёшево и ищет ровно то, что портится в момент письма, — +залог, оценку без факта, жаргон, термин без ввода. Ждать `healthcheck` здесь +нечего: через месяц никто уже не помнит, какую фразу имел в виду автор. -Позови его **последним шагом синка**, отдав список файлов, которых чек-лист -коснулся, — и назови этот список в промпте: по нему же он судит, известен ли -термин. Ничего не правивший синк агента не зовёт. Находки он отдаёт готовыми -формулировками, подставляешь их ты. +Позови его **последним шагом правки, до коммита**, отдав список файлов, которых +она коснулась, — и назови этот список в промпте: по нему же он судит, известен ли +термин. Находки он отдаёт готовыми формулировками, подставляешь их ты. + +**Условие вызова — правка, а не синк.** Синк самый частый вызывающий, но не +единственный: разведка (`av-dev-code:resolve`, сценарий разведки) пишет ответ по +одному адресу и синком себя не считает намеренно — вычитка ей нужна ровно та же. +Признак один и читается буквально: **документы правились — зови, ничего не правил +— не зови**. ## ADR — промоут, а не второе сочинение diff --git a/av-dev-tasks/skills/tasks/SKILL.md b/av-dev-tasks/skills/tasks/SKILL.md index 7d5a268..7814f8f 100644 --- a/av-dev-tasks/skills/tasks/SKILL.md +++ b/av-dev-tasks/skills/tasks/SKILL.md @@ -617,7 +617,8 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап вычитывать до того, как он переписан. Зовутся они **пачкой, а не на каждую запись**: после заведения нескольких задач, -после разбора находок ревью и на переоценке. Передаётся список файлов и — если +после разбора находок ревью, после того как чужая работа уточнила записи (так +делает разведка в `av-dev-code:resolve`), и на переоценке. Передаётся список файлов и — если есть — паспорт, архитектура и конвенции проекта: по ним отличается неизвестный термин от известного.