# Learn from corrections — поправка пользователя → durable правило (capture → distill → enforce)

## Принцип (2026-06-28)

Агент обязан **учиться у пользователя**: каждый раз, когда пользователь правит решение агента,
из этого извлекается урок и кодируется в durable-артефакт (правило / память / хук). Это 4-й рычаг
обучения, который чаще всего упускают (Atai Barkai: «ничто не заменит фидбек из реального
использования»), и операционализация **TRACE** (arXiv 2606.13174): поправки компилируются в правила,
а где возможно — в **хуки**. Память, которую модель может достать, но не обязана соблюдать,
игнорируется в 30–60% случаев (TRACE) → **механический хук > запомненное предпочтение**.

Раньше capture был **ручным** (Session Learning Extraction / `revise-claude-md` — opt-in) и потому
**протекал**: урок терялся, та же поправка давалась повторно. Этот rule делает capture
**автоматическим**, а encode — **полуавтоматическим с human-gate**.

## Петля (3 шага)

1. **Capture (авто, дёшево, детерминированно).** Stop-хук `session-feedback-capture.py` ставит
   завершённую сессию с реальным диалогом (≥2 пользовательских хода) в очередь
   `~/.claude/feedback/queue.jsonl`. Хук **не судит** о содержании — только «была ли движуха,
   которую стоит разобрать». SessionStart-хук `feedback-pending-show.py` показывает счётчик
   незакрытых сессий.
2. **Distill (LLM-семантика, human-gated).** Скилл **`/distill-feedback`** достаёт пользовательские
   ходы (детерминированный `extract_feedback_queue.py`), **семантически** находит durable-поправки
   по рубрике (ниже), дедуплицирует против существующих правил, и **предлагает** атомарные правила
   с условием применимости. **Пользователь утверждает до любой записи** (ACE/TRACE: шумный
   экстрактор отравляет правила; `autonomy-risk-tiers`: правка durable-правил — выше линии
   авто-действия).
3. **Enforce (по 3 тирам TRACE).** Утверждённое правило применяется **delta-merge** (ACE,
   `memory-maintenance.md`: ADD/EDIT, дедуп, без переписывания) в правильный дом
   (`file-organization-cohesion`). Тир выбирается по проверяемости:
   - **детерминированный** — правило механически проверяемо (имя файла, запрещённая команда, форма
     tool-call) → **графадуировать в хук/валидатор** (приоритетно: код детерминирован, прозу
     забывают);
   - **семантический** — LLM-проверка сгенерированного текста (когда детерминированно нельзя);
   - **intent** — runtime-напоминание (rule), когда задача матчит триггер.

## 🔴 Почему детекция — LLM, а НЕ ключевые слова (доказано независимо)

Перед внедрением **независимо протестировали** детектор поправок (Generator-Evaluator, свежий
агент, held-out набор):

| Подход | held-out precision | recall | F1 | soft-поправки |
|---|---|---|---|---|
| Keyword-эвристика | 0.44 | 0.41 | 0.42 | **~0%** |
| **LLM-семантика** | **1.00** | **0.94** | **0.97** | **8/9** |

Keyword-эвристика **отвергнута**: пропускала ~60% реальных поправок (все без ключевого слова:
«в следующий раз лучше через python», «this would've been cleaner as one commit»), а praise-suppress
**убивал** самый частый паттерн — «отлично, но всегда пинуй версии». Keyword-префильтр **структурно
несовместим** с ловлей soft-поправок (отсеет их до LLM). Поэтому детекция = **сам LLM**, по рубрике,
в шаге distill. Доказательная база: `knowledge/agent-systems/self-learning-agents/effectiveness-test/`.

## Рубрика (что есть durable-поправка)

**ДА:** явный pushback/редирект · напоминание о договорённости («мы же договаривались…») · маркер
стоячего предпочтения (always/never/by default/впредь/в следующий раз) · фрустрация на ПОВТОРНУЮ
ошибку (опять/again/you keep) · вежливый редирект вопросом («could you not overwrite X each time?») ·
revert с причиной · **похвала ЗАТЕМ поправка** (судить весь ход целиком).
**НЕТ:** новая фича/запрос · диагностический вопрос · факт/инфо даже со «should be/by default/never» ·
согласие («actually, go ahead») · успокоение («don't worry about the tests») · только похвала · оффтоп.

## Границы / анти-паттерны
- ❌ Авто-применять поправку без human-gate (неверное правило срабатывает на КАЖДОЙ будущей сессии —
  хуже пропущенного).
- ❌ Кодировать one-off как стоячее правило («я имел в виду src, не dist» — разовый фикс).
- ❌ Переписывать файл правил целиком ради вставки (context collapse — `memory-maintenance`).
- ❌ Гонять LLM-distill на каждой сессии без `--limit` (billing: distill — opt-in, по требованию).

## Механически (на хуках, активно)
- `session-feedback-capture.py` (Stop) — авто-очередь сессий, non-blocking, opt-out
  `CLAUDE_SKIP_FEEDBACK_CAPTURE=1` / `~/.claude/.skip-feedback-capture`.
- `feedback-pending-show.py` (SessionStart) — показывает счётчик незакрытых, self-clearing.
- Применение утверждённых правил — `memory-maintenance.md` delta-merge; графадуация в хук — когда
  правило детерминированно проверяемо.

## Related
- `memory-maintenance.md` — delta-merge (ACE), шаг enforce переиспользует его дисциплину; провенанс.
- `autonomy-risk-tiers.md` — правка durable-правил выше линии авто-действия → human-gate.
- `no-guessing.md` — детектор отобран по held-out evidence, не «по интуиции»; Generator-Evaluator.
- `finish-the-task.md` / `quality-over-tokens-independent-verify.md` — урок из сессии доводится до
  durable-артефакта, не теряется; перепроверка свежим агентом.
- Скилл `distill-feedback` — операционка петли (рубрика + процедура + дедуп + апплай).
