av/dev-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

язык: сняты «провенанс» и «интейк», назван образец стиля

Browse Source 
Оба слова стояли в закрытом словаре правила 6 с оговоркой, и обе оговорки
отвергали один русский вариант, а вывод из них делался про все. Отсюда общее
требование к записи словаря: она обязана говорить, чем слово незаменимо, а не
чем плох один из кандидатов. Латинизм, переживший проверку одним синонимом, —
не имя вещи, а непроверенная привычка.

Провенанс заменён двумя словами, потому что смысла было два, и это же его и
держало: происхождение у числа (чем и при каких условиях получено) и откуда у
вопроса и находки (кто нашёл, каким проходом, из какой записи журнала). Слово
стояло и в скелете docs/review.md, уезжающем в репозитории проектов, поэтому
раскладка повышена до версии 4 с записью журнала: правка формы вопроса и
проход grep по docs/.

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

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

Журнал решений: темы 70 и 71, Р258–Р264 и С244–С249. Остальной словарь —
триаж, дедуп, чек-лист, дифф, промпт, чекпоинт, синк — не пересматривался, и
это сказано записью: пересмотр меняет язык всего корпуса и делается своей
работой, а не попутно.
This commit is contained in:
av
2026-08-13 19:43:08 +03:00
parent e78a4311a7
commit e5dc0a1a39
26 changed files with 279 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
av-dev/agents/doc-code-drift.md
+1 -1
View File
@@ -114,7 +114,7 @@ color: green
судит ревью, а не сверка.
**Согласованность документов между собой** — у `doc-consistency`: факт в двух
домах, противоречие между документами, поведение в обзоре, ADR и провенанс.
домах, противоречие между документами, поведение в обзоре, ADR и происхождение чисел.
Увидел — строкой в границы покрытия, находкой не оформляй.
**Язык документов** — у `doc-wording`, **язык записей задач** — у
av-dev/agents/doc-consistency.md
+4 -4
View File
@@ -1,6 +1,6 @@
---
name: doc-consistency
description: "Сверка документов канона между собой и с openspec: один факт, живущий в двух домах, прямое противоречие между документами (периметр, зависимости, обратимость), поведение системы, осевшее в architecture.md вместо спек, capability без обзора или с пересказом требований, число без провенанса в research, ADR без ссылки на источник (архивный design.md либо записка разведки) и без парного статуса при замене, заглушка вместо честной строки в пустом слоте. Читает docs/ и openspec/, кода не читает. Отдаёт готовые формулировки и ничего не правит сам. Соответствие документов коду смотрит агент doc-code-drift, язык — doc-wording. Зовётся скиллом av-dev:doc-healthcheck — на весь канон разом; он же зовётся шагом adopt и шагом upgrade. На отдельной задаче и на синке документации не звать. Только чтение."
description: "Сверка документов канона между собой и с openspec: один факт, живущий в двух домах, прямое противоречие между документами (периметр, зависимости, обратимость), поведение системы, осевшее в architecture.md вместо спек, capability без обзора или с пересказом требований, число без происхождения в research, ADR без ссылки на источник (архивный design.md либо записка разведки) и без парного статуса при замене, заглушка вместо честной строки в пустом слоте. Читает docs/ и openspec/, кода не читает. Отдаёт готовые формулировки и ничего не правит сам. Соответствие документов коду смотрит агент doc-code-drift, язык — doc-wording. Зовётся скиллом av-dev:doc-healthcheck — на весь канон разом; он же зовётся шагом adopt и шагом upgrade. На отдельной задаче и на синке документации не звать. Только чтение."
tools: Read, Grep, Glob
model: opus
color: yellow
@@ -113,10 +113,10 @@ color: yellow
протухший факт. Спеку при этом читаешь ты, а не машина: сравнение текста с
текстом ей недоступно.
5. **Число без провенанса в `research/`.** Замер — с командой или условиями,
5. **Число без происхождения в `research/`.** Замер — с командой или условиями,
которыми получен. Число без источника проход ревью обязан читать как условие,
а не как замер, и это уже записано в каноне; твоя находка — назвать такие
числа поимённо и предложить строку провенанса. **Число, чей источник по
числа поимённо и предложить строку происхождения. **Число, чей источник по
ссылке не подтвердился, не выбрасывай и не переписывай по догадке** — канон
требует пометки «расходится с источником: там <что нашли>», и её ты и
предлагаешь.
@@ -193,7 +193,7 @@ color: yellow
машиной в нём нечего.
Находки по одной, в порядке важности: прямые противоречия → факт в двух домах →
поведение в обзоре → ADR и провенанс → пустые слоты. Первые ломают решения,
поведение в обзоре → ADR и происхождение чисел → пустые слоты. Первые ломают решения,
которые по документам принимают; последние — только цену чтения.
```
av-dev/agents/doc-wording.md
+22 -7
View File
@@ -100,9 +100,7 @@ color: green
| Термин | Что называет |
| --- | --- |
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
| триаж | стадия конвейера, сводящая находки в решение |
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
| дедуп, дедупликация | сверка нового против уже лежащего |
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
| дифф, `--base` | разница между состояниями в git |
@@ -119,9 +117,26 @@ color: green
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
набор), **гайд** (руководство), **опиниативный** (проход с мнением). Каждое
было латинизмом или калькой при живом русском слове, и каждое к моменту снятия
жило в трёх-шести файлах разом — то есть выглядело словарём, не будучи им.
набор), **гайд** (руководство), **опиниативный** (проход с мнением),
**провенанс** (происхождение числа: чем и при каких условиях получено),
**интейк** (заведение записей — из диалога, из ревью: операция зовётся своим
источником). Каждое было латинизмом или калькой при живом русском слове, и
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
словарём, не будучи им.
**Провенанс и интейк сняты из самого словаря, и это прецедент.** Оба стояли в
нём с оговоркой, и обе оговорки были верны, но доказывали меньше, чем от них
брали.
| Слово | Чем защищалось | Чем заменено |
| --- | --- | --- |
| провенанс | «источник» рядом называет саму запись, а не свойство | **происхождение** у числа, **откуда** у вопроса и находки: смысла было два, и это же и держало латинизм |
| интейк | «заведение» называет создание файла, а не отбор с дедупом | **заведение с названным источником** — «из диалога», «из ревью»: так операция и называется в самом скилле задач |
Общее у обоих: оговорка отвергала **один** русский вариант, а вывод делался
про все. **Латинизм, переживший проверку одним синонимом, — не имя вещи, а
непроверенная привычка**, и запись в словаре обязана говорить, чем слово
незаменимо, а не чем плох один из кандидатов.
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
читателю — нет.
@@ -170,7 +185,7 @@ color: green
Величина нужна читателю редко, а когда нужна — её называет сам корпус в
момент чтения: каталог, индекс, команда. Абзац её только запоминает.
**Замер с провенансом — не счёт корпуса.** «Прозаический триггер дал 6
**Замер с названным происхождением — не счёт корпуса.** «Прозаический триггер дал 6
записей ADR на 43 изменения» описывает прошлое, а прошлое не пополняется: это
факт по правилу 2, и трогать его нельзя. Разница проверяется вопросом
«изменится ли число само, без правки текста».
@@ -212,7 +227,7 @@ color: green
**Чужому подрядчику — строкой в границах покрытия.** Согласованность документов
между собой (факт в двух домах, противоречие, поведение, осевшее в обзоре, ADR
без ссылки, число без провенанса) — у `doc-consistency`; соответствие документов
без ссылки, число без происхождения) — у `doc-consistency`; соответствие документов
коду — у `doc-code-drift`; язык записей каталога задач — у `task-wording`, их
форма — у `task-form`. Увидел — назови в конце одной строкой, чтобы находка не
пропала, но находкой не оформляй.
av-dev/agents/review-triage.md
+1 -1
View File
@@ -177,7 +177,7 @@ severity:
любой метке и `review-basics`, когда запускается. Пришёл хоть от одного — веди
его в сводку отдельной строкой, а не в общий список находок: метку выбирал
`review-scope`, а не они и не ты, значит сигнал независим. Пришли оба — это одна
строка с двумя провенансами, а не два пункта: согласие проходов приоритет
строка с двумя названными проходами, а не два пункта: согласие проходов приоритет
повышает, `confidence` нет.
**Сигнала нет — тоже скажи строкой.** «Корректор метки отработал, возражений
av-dev/agents/task-wording.md
+21 -6
View File
@@ -107,9 +107,7 @@ color: green
| Термин | Что называет |
| --- | --- |
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
| триаж | стадия конвейера, сводящая находки в решение |
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
| дедуп, дедупликация | сверка нового против уже лежащего |
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
| дифф, `--base` | разница между состояниями в git |
@@ -126,9 +124,26 @@ color: green
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
набор), **гайд** (руководство), **опиниативный** (проход с мнением). Каждое
было латинизмом или калькой при живом русском слове, и каждое к моменту снятия
жило в трёх-шести файлах разом — то есть выглядело словарём, не будучи им.
набор), **гайд** (руководство), **опиниативный** (проход с мнением),
**провенанс** (происхождение числа: чем и при каких условиях получено),
**интейк** (заведение записей — из диалога, из ревью: операция зовётся своим
источником). Каждое было латинизмом или калькой при живом русском слове, и
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
словарём, не будучи им.
**Провенанс и интейк сняты из самого словаря, и это прецедент.** Оба стояли в
нём с оговоркой, и обе оговорки были верны, но доказывали меньше, чем от них
брали.
| Слово | Чем защищалось | Чем заменено |
| --- | --- | --- |
| провенанс | «источник» рядом называет саму запись, а не свойство | **происхождение** у числа, **откуда** у вопроса и находки: смысла было два, и это же и держало латинизм |
| интейк | «заведение» называет создание файла, а не отбор с дедупом | **заведение с названным источником** — «из диалога», «из ревью»: так операция и называется в самом скилле задач |
Общее у обоих: оговорка отвергала **один** русский вариант, а вывод делался
про все. **Латинизм, переживший проверку одним синонимом, — не имя вещи, а
непроверенная привычка**, и запись в словаре обязана говорить, чем слово
незаменимо, а не чем плох один из кандидатов.
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
читателю — нет.
@@ -177,7 +192,7 @@ color: green
Величина нужна читателю редко, а когда нужна — её называет сам корпус в
момент чтения: каталог, индекс, команда. Абзац её только запоминает.
**Замер с провенансом — не счёт корпуса.** «Прозаический триггер дал 6
**Замер с названным происхождением — не счёт корпуса.** «Прозаический триггер дал 6
записей ADR на 43 изменения» описывает прошлое, а прошлое не пополняется: это
факт по правилу 2, и трогать его нельзя. Разница проверяется вопросом
«изменится ли число само, без правки текста».
av-dev/shared/config.py
+1 -1
View File
@@ -56,7 +56,7 @@ LEGACY_TASKS = ".tasks.json"
# Версия раскладки — одна на плагин. Журнал версий — references/changelog.md
# скилла `canon`, повышает его операция `upgrade`.
VERSION = 3
VERSION = 4
VERSION_KEY = "version"
av-dev/shared/language.md
+50 -6
View File
@@ -47,6 +47,35 @@
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
а это и есть цена, которой мы избегаем.
## Образец: научно-популярная книга
**Так, как пишут хорошую научно-популярную книгу.** Не спецификация, не статья в
блоге, не конспект для себя: текст, который объясняет устройство **точными
простыми словами** и понятен с первого прохода тому, кто эту систему не писал.
Из образца следуют три умолчания, и все три — про плотность, а не про красоту:
- **воды нет.** Каждая фраза несёт сведение: что устроено так, почему так и что
из этого следует. Абзац, из которого ничего нельзя достать, вычёркивается
целиком, а не переписывается;
- **сложных конструкций нет.** Причастный оборот внутри придаточного, три
отрицания подряд, предложение на пять строк — читатель разбирает такую фразу
дважды, и второй раз он её уже не разбирает. Причинную связь при этом не
режут: «поэтому», «иначе», «раз так» — сведения;
- **англицизм — исключение, требующее причины.** Умолчание обратное принятому в
разработке: пишем по-русски, а иностранное слово остаётся, только когда оно
**имя вещи** или когда русский аналог искажает смысл. Какая причина годится,
разбирает правило 5; закрытый список принятых слов — правило 6.
Термин здесь не запрещён — запрещена **перегрузка**: термин, который вводится
одной строкой, дешевле описания в три предложения, а термин, который
предполагается известным, дороже обоих (правило 8).
**Образец находок не порождает.** Он для того, кто пишет; вычитка судит по
правилам, и правка без нарушенного правила не делается (раздел «Порог правки»).
Иначе «мне кажется, звучит сложно» стало бы находкой, и список замечаний
перестали бы читать целиком.
## Что взято сверх правил вычитки
Эти три требования судит человек, а не проход вычитки: находка по ним требует
@@ -158,9 +187,7 @@
| Термин | Что называет |
| --- | --- |
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
| триаж | стадия конвейера, сводящая находки в решение |
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
| дедуп, дедупликация | сверка нового против уже лежащего |
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
| дифф, `--base` | разница между состояниями в git |
@@ -177,9 +204,26 @@
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
набор), **гайд** (руководство), **опиниативный** (проход с мнением). Каждое
было латинизмом или калькой при живом русском слове, и каждое к моменту снятия
жило в трёх-шести файлах разом — то есть выглядело словарём, не будучи им.
набор), **гайд** (руководство), **опиниативный** (проход с мнением),
**провенанс** (происхождение числа: чем и при каких условиях получено),
**интейк** (заведение записей — из диалога, из ревью: операция зовётся своим
источником). Каждое было латинизмом или калькой при живом русском слове, и
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
словарём, не будучи им.
**Провенанс и интейк сняты из самого словаря, и это прецедент.** Оба стояли в
нём с оговоркой, и обе оговорки были верны, но доказывали меньше, чем от них
брали.
| Слово | Чем защищалось | Чем заменено |
| --- | --- | --- |
| провенанс | «источник» рядом называет саму запись, а не свойство | **происхождение** у числа, **откуда** у вопроса и находки: смысла было два, и это же и держало латинизм |
| интейк | «заведение» называет создание файла, а не отбор с дедупом | **заведение с названным источником** — «из диалога», «из ревью»: так операция и называется в самом скилле задач |
Общее у обоих: оговорка отвергала **один** русский вариант, а вывод делался
про все. **Латинизм, переживший проверку одним синонимом, — не имя вещи, а
непроверенная привычка**, и запись в словаре обязана говорить, чем слово
незаменимо, а не чем плох один из кандидатов.
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
читателю — нет.
@@ -228,7 +272,7 @@
Величина нужна читателю редко, а когда нужна — её называет сам корпус в
момент чтения: каталог, индекс, команда. Абзац её только запоминает.
**Замер с провенансом — не счёт корпуса.** «Прозаический триггер дал 6
**Замер с названным происхождением — не счёт корпуса.** «Прозаический триггер дал 6
записей ADR на 43 изменения» описывает прошлое, а прошлое не пополняется: это
факт по правилу 2, и трогать его нельзя. Разница проверяется вопросом
«изменится ли число само, без правки текста».
av-dev/skills/canon/SKILL.md
+1 -1
View File
@@ -108,7 +108,7 @@ capability: незаполненный канон это переходное с
| Агент | Что смотрит | Читает |
| --- | --- | --- |
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` |
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без происхождения, заглушка вместо честной строки | `docs/`, `openspec/` |
| `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий |
Судит **не тот, кто писал**: самопроверка документа слабее всего ровно там, где
av-dev/skills/canon/references/canon.md
+4 -4
View File
@@ -53,7 +53,7 @@ docs/
database.md | database/ схема хранилища; представление данных и настройки
security.md | security/ периметр; недоверенный вход; что вне модели
conventions.md | conventions/ как пишем код; что механизировано
research.md | research/ наблюдения и числа с провенансом
research.md | research/ наблюдения и числа с происхождением
adr.md | adr/ почему решено так; статусы, правило замены
review.md | review/ настройка конвейера под проект + журнал дефектов
<своя тема>.md | <своя тема>/ всё, что проект счёл нужным проверять
@@ -127,7 +127,7 @@ openspec/
**Процессный документ — не документ второго сорта.** `adr/` и `research/`
проверяются наравне с остальными, но **сверкой документации**, а не прогоном
ревью: ADR без ссылки на источник, замена без парного статуса, число
без провенанса — это работа агентов `doc-consistency` и `doc-code-drift`, и она
без происхождения — это работа агентов `doc-consistency` и `doc-code-drift`, и она
осталась там же, где была. Изменилось одно: прогон ревью не открывает их как
критерий и не судит по ним изменение.
@@ -267,7 +267,7 @@ kebab-case.** Причина не эстетическая: имя файла с
Наблюдения за внешним миром: что реально шлёт источник, чем документация формата
расходится с практикой, какие числа сняты с живого потока. **Числа — с
провенансом**, то есть с командой или условиями, которыми получены.
происхождением**, то есть с командой или условиями, которыми получены.
`README.md` — как снималось и индекс тем.
Число без источника проход обязан читать как условие, а не как замер. Число, чей
@@ -318,7 +318,7 @@ kebab-case.** Причина не эстетическая: имя файла с
- **Типовые узлы** — рода узлов проекта и 3–5 проверяемых свойств к каждому;
- **Типовые ложноположительные** — находки, которые здесь выглядят убедительно и
всегда неверны, каждая со строкой «почему здесь это не дефект»;
- **Вопросы по темам** — в форме `<тема>: <вопрос> (<провенанс>)`. **Не по именам
- **Вопросы по темам** — в форме `<тема>: <вопрос> (<откуда>)`. **Не по именам
проходов**: проход уезжает между метками, а тема остаётся, и вопрос,
адресованный проходу, перестал бы задаваться молча в тот день, когда тот уехал
в старшую метку. Задаёт вопрос тот, кто закрывает тему на этом прогоне.
av-dev/skills/canon/references/changelog.md
+31
View File
@@ -22,6 +22,37 @@
---
## Версия 4 — 2026-08-13
Слово **провенанс** снято из словаря языка проектных текстов и заменено русским.
Оно стояло в закрытом списке своих терминов с оговоркой «„источник“ рядом
называет саму запись, а не свойство» — верной, но доказывающей лишь то, что не
годится одно русское слово. Годятся два, и по смыслу они разные: **происхождение**
у числа (чем и при каких условиях получено) и **откуда** у вопроса или находки
(кто нашёл, каким проходом, из какой записи журнала).
**Что переехало в проекте.** Скелет `docs/review.md`, подраздел «Вопросы по
темам»: форма вопроса записана как `<тема>: <вопрос> (<откуда>)` вместо
`(<провенанс>)`. Само правило — в [canon.md](canon.md), раздел `review.*`;
требование к числам `research/` не изменилось по существу, изменилось слово.
**Что сделать проекту.**
1. **Поправить форму в `docs/review.md`** — строка «Форма: `<тема>: <вопрос>
(<провенанс>)`» становится «Форма: `<тема>: <вопрос> (<откуда>)`». Уже
записанные вопросы переписывать не надо: слово стояло в шаблоне, а не в них.
2. **Пройти по документам** — `grep -rn "провенанс" docs/`. Найденное в
`research/` и в `adr/` заменяется на **происхождение** (речь о числе) или на
**откуда** (речь о том, из чего вопрос или находка выросли). Ничего не
нашлось — шаг закрыт строкой, это обычный исход.
3. **Поднять версию** — `docs.py bump`, последним шагом.
4. `docs.py check` — до отсутствия дрейфа.
**Чего делать не надо.** Править прошлые записи журналов и архивные change:
слово, верное на день записи, остаётся верным как свидетельство.
---
## Версия 3 — 2026-08-13
Тип записи `goal` и индекс `ROADMAP.md` упразднены; у проекта появилась
av-dev/skills/canon/references/skeletons.md
+1 -1
View File
@@ -283,7 +283,7 @@
### Вопросы по темам
Форма: `<тема>: <вопрос> (<провенанс>)`. Главный источник — журнал ниже. Вопрос
Форма: `<тема>: <вопрос> (<откуда>)`. Главный источник — журнал ниже. Вопрос
задаёт тот проход, который закрывает эту тему на текущем прогоне, дополнительно
к обязательным.
av-dev/skills/code-resolve/references/research.md
+5 -5
View File
@@ -105,7 +105,7 @@ git и читается диффом, а второй стоп на каждой
требующий кода, — это отдельная задача, и её нужно назвать, а не написать по
ходу. Исключение ровно одно и оно не про изменение системы: одноразовый
**читающий** прогон (запрос, замер, скрипт в песочнице), чей результат уезжает
в ответ с провенансом и который ничего не оставляет в репозитории.
в ответ с происхождением и который ничего не оставляет в репозитории.
- **Местом в списке.** Заведённая задача встаёт в конец своей секции; куда её
поставить, решает человек — на доработке грумингом (`av-dev:task-groom`), на
стройке сразу же, по зависимости. Разведка, сама ставящая свой исход первым,
@@ -145,7 +145,7 @@ git и читается диффом, а второй стоп на каждой
1. **ответ записан по адресу, который назвала задача** — раздел «Куда ляжет
ответ». Адреса не было, а вопрос был — ты назначил адрес сам и сказал об этом
строкой;
2. **у каждого числа провенанс** — команда или условия, которыми оно получено.
2. **у каждого числа названо происхождение** — команда или условия, которыми оно получено.
Число без источника проход ревью обязан читать как условие, а не как замер, и
разведка, оставившая голые числа, вредна: по ним будут решать;
3. **отвергнутые варианты названы с причиной**. Отвергнутое без причины
@@ -176,7 +176,7 @@ git и читается диффом, а второй стоп на каждой
| Что узнали | Дом ответа |
| --- | --- |
| наблюдение о внешнем мире, замер с провенансом | `docs/research/` |
| наблюдение о внешнем мире, замер с происхождением | `docs/research/` |
| решение с ценой: намеренный отказ, дорогой откат | `docs/adr/` |
| факт об устройстве системы | тема `architecture` (или своя тема проекта) |
| граница домена, «чем проект **не** является» | `passport` |
@@ -199,7 +199,7 @@ git и читается диффом, а второй стоп на каждой
2. **код и его история** — `git log` по узлу отвечает на «почему так» чаще, чем
кажется;
3. **внешние источники** — документация формата, чужой опыт, спецификации;
4. **замер** — если вопрос про числа. Числа снимаются с провенансом, иначе они
4. **замер** — если вопрос про числа. Числа снимаются с происхождением, иначе они
бесполезны на следующем шаге.
**Скилл `opsx:explore`** — законный инструмент этого шага, если плагин в проекте
@@ -253,7 +253,7 @@ git и читается диффом, а второй стоп на каждой
### 4. Ответ в документы канона
**Вызови Skill `av-dev:doc-sync`**: он владеет содержимым документов канона.
Передай ему ответ, адрес из шага 1 и провенанс каждого числа — писать содержание
Передай ему ответ, адрес из шага 1 и происхождение каждого числа — писать содержание
за тебя он не будет, но дом и форму держит он. Вычитка языка — тоже его агент, но
момент её назван отдельно, шагом 6: пачка собирается из шагов 4 и 5 и до конца
пятого не полна.
av-dev/skills/code-resolve/references/solve.md
+2 -2
View File
@@ -316,7 +316,7 @@ flowchart TD
**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для
этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада
`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не этот
`Урожай`: формулировка, оракул, откуда взялась. Задачи из него **заводит не этот
скилл** — их заводит `av-dev:task-track` своим сценарием «задачи из ревью и
аудита»: своя нарезка, свой формат, свои правила дублей. Твоя обязанность — не
потерять и передать.
@@ -401,7 +401,7 @@ change. Заводить запись задним числом, чтобы её
- ссылка на архивный change и хеш коммита;
- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход** —
это доклад приёмщику, а не отметка «принято»;
- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс);
- **`Урожай`** — отложенные находки списком (формулировка, оракул, откуда взялась);
- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы не
запускались и что проверить было невозможно. Доклад без неё сообщает
«проверено», не сообщая, что именно.
av-dev/skills/code-review/SKILL.md
+1 -1
View File
@@ -1043,7 +1043,7 @@ flowchart TD
останавливается: он урезает изменение до остатка и доводит его.
- Находка не для этого мерджа, но реальная (отложенный `major`, развилка,
решённая «потом»), — не теряется, но **и не заводится здесь**. Конвейер отдаёт
её **списком урожая** в отчёте: формулировка, оракул, провенанс (какой проход,
её **списком урожая** в отчёте: формулировка, оракул, откуда взялась (какой проход,
какой change). Заведение задач принадлежит `av-dev:task-track` — зови его со
списком урожая, у него на этот вход отдельный сценарий «задачи из ревью и
аудита»: свой формат, кластеризация по причине, дедуп против беклога и
av-dev/skills/code-review/references/project-facts.md
+1 -1
View File
@@ -125,7 +125,7 @@
- **Читай в источнике, не по памяти.** Документы правятся по ходу работы, в том
числе этой же задачей.
- **Число без провенанса — условие, а не утверждение.** Число, чей источник по
- **Число без происхождения — условие, а не утверждение.** Число, чей источник по
ссылке не подтвердился, читается как условие и **называется расходящимся**, а
не подменяется догадкой.
- **Пустое, названное пустым, — это факт.** «Внешних зависимостей нет — смотри
av-dev/skills/doc-healthcheck/SKILL.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: doc-healthcheck
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
---
# Здоровье документации
@@ -89,7 +89,7 @@ check` и его скрипт; здесь начинается там, где к
| Агент | Что смотрит | Читает | Модель |
| --- | --- | --- | --- |
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` | `opus` |
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без происхождения, заглушка вместо честной строки | `docs/`, `openspec/` | `opus` |
| `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий | `sonnet` |
**`doc-code-drift` обязан получить раздел запретов `CLAUDE.md`.** Он гоняет
av-dev/skills/doc-sync/SKILL.md
+1 -1
View File
@@ -135,7 +135,7 @@ description: Вести содержимое документов канона
## Запись в `research/`
Наблюдение о внешнем мире: что реально шлёт источник, чем документация формата
расходится с практикой. **Требование провенанса и правило про расходящееся
расходится с практикой. **Требование происхождения и правило про расходящееся
число — в [каноне](../canon/references/canon.md), раздел `research/`.**
Твоя часть — заметить, что по ходу задачи узналось новое о внешних данных, и не
av-dev/skills/task-groom/SKILL.md
+2 -2
View File
@@ -72,8 +72,8 @@ description: "Груминг беклога — интерактивный ра
**Зовёт человек.** Скилл сам себя не назначает, но обязан **напоминать**, и
признак наблюдаемый, а не календарный:
- в беклоге появились записи, которых человек ещё не видел (заведены интейком по
ходу работы, урожаем ревью, разбором находок);
- в беклоге появились записи, которых человек ещё не видел (заведены по ходу
работы, урожаем ревью, разбором находок);
- на верхних строках очереди есть задача с открытым вопросом — очередь
показывает то, что взять нельзя;
- `tasks.py check` печатает «готово к взятию: 0 из N» — брать сегодня нечего.
av-dev/skills/task-groom/references/portions.md
+2 -2
View File
@@ -64,10 +64,10 @@
решение>"`. Задача закрывается не только коммитом.
3. **Проверь пересечения.** Две задачи об одном — содержимое в одну, вторую
`close <slug> --reason "слита с <другой-слаг>"`. Смотри **шире порции**:
интейк дедуплицирует новое против существующего, но никогда не пересматривает
заведение сверяет новое против уже лежащего, но никогда не пересматривает
уже лежащее, и две задачи с одной причиной могут лежать рядом месяцами.
4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами
одного дефекта, сливаются в одну — это находка, которую интейк дать не мог.
одного дефекта, сливаются в одну — это находка, которую заведение дать не могло.
5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство
репозитория в рамках, предписание процесса в теле, тип, разошедшийся с
задачей, границы вместо реализации в разделе «Затрагивает». Список и правила —
av-dev/skills/task-track/SKILL.md
+1 -1
View File
@@ -724,7 +724,7 @@ python3 $tk adopt scan --from … --stage S | apply --plan … # разова
- **Не больше трёх вопросов за раз.** Пачка длиннее трёх тяжела для ответа;
решений больше — веди **несколько итераций** диалога по ≤3, а не один
перегруженный запрос. Между итерациями применяй уже решённое.
- **Границы покрытия в отчёте.** Любая сессия разбора, штурма или интейка
- **Границы покрытия в отчёте.** Любая сессия разбора, штурма или заведения записей
заканчивается строкой «просмотрено N из M, не трогали — …». Отчёт без неё
сообщает «беклог разобран», не сообщая, какая его часть осталась нетронутой.
- **Ничего не удаляем молча.** Файл исчезает только через `close` — `--reason`
av-dev/skills/task-track/references/adopt.md
+1 -1
View File
@@ -18,7 +18,7 @@
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, в каком
порядке разложилось и **что не разложилось**, — и только после подтверждения
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
пишется хоть один файл. Это то же правило, что у заведения задач из ревью:
массовое заведение записей без подтверждения — самый дорогой отказ, потому
что разгребает его потом переоценка.
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
av-dev/skills/task-track/references/from-review.md
+14 -11
View File
@@ -2,10 +2,13 @@
Ревью и аудиты — код-ревью, архитектурный проход, аудит безопасности, любой
разбор другим агентом — порождают находки, часть которых становится задачами.
Это отдельный интейк со своей опасностью, **зеркальной** интейку из диалога.
Это отдельное **заведение записей** со своей опасностью, **зеркальной**
заведению из диалога. Операция зовётся по источнику, потому что источник и
задаёт опасность.
- Интейк из диалога грешит переполнением: из одной мысли рождается пять файлов.
- Интейк из ревью грешит сваливанием: сорок сырых находок превращаются в сорок
- Заведение из диалога грешит переполнением: из одной мысли рождается пять
файлов.
- Заведение из ревью грешит сваливанием: сорок сырых находок превращаются в сорок
файлов. Беклог раздувается, а следующая переоценка склеивает их обратно.
Защита от сваливания — та же, что в самом ревью: **кластеризация по причине, а
@@ -14,7 +17,7 @@
**Штатный отправитель — `av-dev:code-review`** (и `av-dev:code-resolve`, который
его вызывает): задач он не заводит сам, а отдаёт отложенные находки **списком
урожая** — формулировка, оракул, провенанс — и хранит отчёт триажа вместе с
урожая** — формулировка, оракул, откуда взялась — и хранит отчёт триажа вместе с
изменением. Приходит и любой другой разбор, вплоть до пересказа человеком; тогда
триажа нет и шаг 1 порядка делается руками.
@@ -56,9 +59,9 @@
«заказать или убрать». Выноси такую пользователю отдельно от прочих.
5. **Покажи карту до создания файлов.** Кластер → задача / сырьё / строка в
пакетный файл / уже заведено / отброшено — пачкой через
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
диалога: массовое заведение файлов без подтверждения — ровно тот отказ, ради
которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» при заведении
из диалога: массовое заведение файлов без подтверждения — ровно тот отказ,
ради которого заведение из ревью и выделено. Дешёвая мелочь по явному согласию может
заводиться и без поштучного вопроса — но карта пользователю предъявляется
всё равно.
6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
@@ -70,7 +73,7 @@
`research`. Тип, розданный оптом, врёт ровно там, где по нему потом
отбирают, **и требует не тех разделов**: каждому `fix` придётся заполнить
`Воспроизведение`, а у находки без свидетельства его нет;
- **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством.
- **откуда взялась — в теле**: кто нашёл, каким проходом, с каким свидетельством.
Без него через месяц не отличить проверенную находку от догадки.
7. `tasks.py check`.
@@ -79,7 +82,7 @@
Уровня серьёзности в записи нет — но **выкидывать её нельзя**: серьёзность
отображается **в позицию в очереди**, потому что приоритет и есть порядок строк
в беклоге (правило 4 [SKILL.md](../SKILL.md)). Отображается через довод, а не
напрямую: своей шкалы у интейка нет, доводы расстановки перечислены в
напрямую: своей шкалы у заведения нет, доводы расстановки перечислены в
[скилле груминга](../../task-groom/SKILL.md#приоритет-как-его-расставляют), и
серьёзность попадает ровно в один из них.
@@ -103,7 +106,7 @@
(`--reason`). Позицию назначит человек на ближайшем груминге, сравнив её с
верхом очереди; без записанного довода сравнивать он будет с нуля;
- **находка, которая не ждёт груминга вовсе** (необратимый ущерб, покраснела
проверка, которую проект назвал сломанным), — не интейк: это работа прямо
проверка, которую проект назвал сломанным), — не заведение записи: это работа прямо
сейчас, а в беклог она падает, только если ждать всё-таки можно;
- **низкая уверенность или нет свидетельства** → сырьё (`research` с пустым
разделом «Вопрос»): его место в очереди производно от типа — конец секции;
@@ -115,7 +118,7 @@
## Поимённая сверка
Интейк считается выполненным, только если **каждая** находка триажа получила
Заведение считается выполненным, только если **каждая** находка триажа получила
исход: слаг заведённой задачи, ссылку на существующую, строку пакетного файла
или запись «не заведена: причина». Нулевой урожай при непустом отчёте триажа
виден сразу — и это единственный способ отличить «находок не было» от «не стал
av-dev/skills/task-track/references/task-research.md
+1 -1
View File
@@ -64,7 +64,7 @@
3. **Ограничить рамками**, если разведка может утечь: сколько времени, какие
источники, что заведомо вне.
4. **Провести разведку** и **записать ответ по названному адресу**. Числа — с
провенансом: с командой или условиями, которыми получены. Число без источника
происхождением: с командой или условиями, которыми получены. Число без источника
проход ревью обязан читать как условие, а не как замер. Проводит её конвейер
проекта — скилл `av-dev:code-resolve`, сценарий разведки; этот скилл её
только заводит и закрывает.