Harvest Canon

---
name: harvest-canon
description: Вынести находку сессии в канон брифом проактивно: сбой пришлось объяснять, найден обходной путь, пользователь исправил вывод. Не для проектной специфики; доработку в бэклог кладет `backlog-task`.
---

# Кристаллизация приема в канон

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

## Когда применять

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

Момент срабатывания - **наблюдаемое событие, а не ощущение ценности**:

- **пришлось объяснять сбой**, механика которого не следует из документации;
- **понадобился обходной путь** из-за поведения инструмента, а не задачи;
- **пользователь исправил вывод агента и НЕ назвал причину словами** - поправка вида "нет, там иначе" без объяснения. Причину, проговоренную словами, забирает ночной сборщик, см. ниже;
- **действие пользователя потрачено впустую** по нашему совету (перезапустил, переавторизовался, переслал - и не помогло).

Дальше порядок такой:

1. **Складывать находки по ходу пунктом в `TodoWrite`**, а не держать в голове: сессия на несколько часов переживет компакт, память о находке - нет. В автопамять их класть нельзя - там durable-факты, а не прогресс задачи (`rules/memory-persistence.md`).
2. **Перед тем как предложить, прогнать находку через "Когда НЕ применять" ниже.** Без этого шага перечисленные события срабатывают чаще, чем скилл допускает, и в очередь поедет проектная специфика.
3. **В конце задачи - одна строка с предложением**, а не готовый бриф: оформлять решает пользователь. Нештатного не было - **молчать**: строка "находок нет" это постамбула, запрещенная `rules/compact-results.md`.

Граница с ночным сборщиком поправок (`/feedback-inbox`) проходит по одному признаку: **проговорена ли причина словами**. Проговорена ("так не надо, потому что...", "ты неверно понял задачу") - это его добыча, дублировать не надо. Не проговорена - грабли инструмента, обходной путь, молчаливая поправка - твоя: сборщик читает реплики и такого не увидит.

## Когда НЕ применять

- **Прием разовый.** Проверка простая: пригодится ли он в проекте, где нет ни этого сервера, ни этой задачи. Нет - место в памяти проекта: канон раскатывается по всем проектам, и лишний файл там дороже отсутствующего.
- **Прием уже в каноне** - сначала проверить; кандидат-дубль тратит разбор впустую. Разошедшаяся копия канон-файла это не кандидат, а повод синкнуться.
- **Стандартная практика из документации инструмента** - канон фиксирует то, что мы выяснили сами и чего в README нет.
- **Нет отработавшего опыта** - "хорошо бы так делать" без единого прогона не кандидат: канон описывает проверенное, иначе он копит гипотезы.

## Критерий "достоин канона"

Прием заслуживает вынесения, если одновременно:

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

Не создавай канон-актив под one-off решение, стандартную задокументированную практику или факт, ценный только для текущего проекта, - последнее остается в памяти.

## Одна техника - один актив

Не смешивай несколько приемов в одном файле. Если находка распадается на два независимых полезных факта - оформляй раздельно.

## Правка существующего актива (amend)

Если находка - не новый прием, а дефект или пробел уже существующего канон-актива (скилл на практике сработал криво, правило вводит в заблуждение, шаг устарел) - кандидат оформляется как правка этого актива, не как новый. Дефолт - патч существующего файла; почти одинаковых скиллов-близнецов не плодить.

Amend-кандидат оформляется и регистрируется той же схемой, что описана в "Как оформить", - отличается только содержимое брифа: вместо депроектированного содержимого целиком в нем канонический путь правимого актива, конкретный случай сбоя (что ожидалось по тексту актива / что вышло фактически), минимальная предлагаемая дельта и критерий регрессии (как проверить, что после правки случай закрыт).

## Развилка: скилл vs правило vs память

- **Скилл** - переносимая процедура "как делать X": последовательность шагов, чек-лист, техника с точками принятия решений. Годится, когда прием - это метод действия.
- **Правило** - постоянное поведенческое ограничение "всегда/никогда делай Y", без пошаговой процедуры. Годится, когда прием - это граница, а не метод.
- **Память** - проектный факт (архитектурное решение, конкретный баг и его фикс, состояние конкретной системы). Не переносится в канон, остается в памяти текущего проекта.

При сомнении между скиллом и правилом: если находку можно записать одной директивой без шагов - правило; если нужна процедура с развилками - скилл.

## Депроектирование перед оформлением

Прежде чем оформлять находку, вычисти из нее специфику текущего проекта: конкретные пути, домены, имена систем, названия серверов. Замени на нейтральные формулировки и абстрактные примеры. Если прием без этой специфики теряет смысл (намертво привязан к одной системе) - он не канон-кандидат, а остается в проекте.

## Как оформить

Канон-актив не идет прямым изменением в клон канона. Оформи промпт-кандидат **одной командой** - `python3 scripts/canon-brief.py deliver --name <имя> < текст.md`: она положит бриф и в очередь канона, и в `toolkit-log/upstream-pending/<имя>.md` текущего проекта. Файл руками не создавай (`upstream-inbox.md`: ручная запись - это ровно тот путь, которым теряются находки). Бриф должен быть самодостаточным для будущей сессии в клоне канона, которая отревьюит, доработает и вольет находку. Кандидат содержит: происхождение (проект, дата, тип), предлагаемый путь в каноне, депроектированное содержимое целиком, обоснование (какой пробел закрывает и почему полезно любому проекту) и ран-лист действий для сессии в клоне.

Зарегистрируй кандидата в реестре синка - но **только когда файл брифа лежит в `toolkit-log/upstream-pending/`**: при коде 2 его нет нигде, при коде 3 нет локальной копии, и запись с `brief_path` в никуда даст осиротевшую строку, которую потом придется разбирать руками (что делать при 2 и 3 - ниже). Без записи синк не отследит находку: когда она доедет в канон, пометка не вычистится и бриф зависнет сиротой в `upstream-pending/`. Реестр зависит от схемы проекта:

- **canon-fleet** (в проекте есть `.claude/canon.ledger.json`) - допиши в его список `upstream_pending` запись `{"candidate_id": "<sha256 содержимого файла брифа>", "brief_path": "toolkit-log/upstream-pending/<имя>.md", "source": "harvest-canon"}` (хеш - `shasum -a 256 <файл брифа>`). Перед добавлением проверь, нет ли уже записи с тем же `brief_path`: повторный прогон на той же находке не плодит дубль (содержимое брифа между прогонами меняется, поэтому дедуп - по `brief_path`, не по хешу); если бриф при этом переписан - обнови `candidate_id` существующей записи на sha256 новых байт, иначе id останется от старого содержимого. Если ledger есть, но JSON не парсится или списка `upstream_pending` в нем нет - реестр битый: не чини его и запись не добавляй, сообщи пользователю (тот же критерий битости, что у синка).
- **legacy** (только `.claude/canon.yaml`) - допиши в его список `upstream_pending` предполагаемый канонический путь (напр. `skills/foo/SKILL.md`); если такой путь уже в списке - не дублируй.

В обеих схемах имя файла брифа `<имя>` выведи из предполагаемого канонического пути (как slug, напр. `skills-foo`).

## Доставка: делает скрипт, проверяешь код возврата

Обе копии кладет `canon-brief.py deliver` из шага выше - отдельного действия "доставить" больше нет, и забыть его нельзя. Что остается на тебе: **посмотреть код возврата и сказать результат пользователю одной строкой**.

- `0` - оформлен и доставлен, дальше реестр;
- `2` - очередь не записана, бриф НЕ доставлен: говорить прямо, находка под угрозой; реестр не трогать;
- `3` - в очереди есть, локальной копии нет. Сперва `canon-brief.py check --restore-local`, и только после этого реестр: без файла `brief_path` укажет в никуда, а `shasum` считать не с чего. Не восстановилось - скажи пользователю и реестр не трогай.

Правила именования, замены прежней версии, фиксированности адреса и случай "клона канона на этой машине нет" - в `upstream-inbox.md`; скрипт их исполняет, читать их нужно, чтобы понимать его вывод.

Оригинал в `toolkit-log/upstream-pending/` остается на месте - он источник для синка и история проекта.

## Отличие от синка канона

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

См. также `rules/docs-maintenance.md` (там - как поддерживать актуальность документации внутри проекта; здесь - как поднять переиспользуемую находку из проекта в общий канон).