/knowledge-compiler

Compilation Playbook

Цель — собрать не "книгу покороче", а рабочую механику мышления по источнику.

Слои результата

1. Понятия — как источник называет важные сущности.
2. Решающие правила — когда какое действие выбрать.
3. Плейбуки — повторяемые сценарии применения.
4. Анти-паттерны — признаки ошибки и почему она возникает.
5. Диагностические вопросы — как агент должен уточнять задачу пользователя.
6. Карта источников — откуда взят каждый тезис.

Разведка структуры

Перед сегментацией используй uv run --script scripts/outline_scout.py. Скрипт создаёт компактный артефакт:

• outline-scout.json — метаданные, наблюдения скрипта и место для решения модели;
• outline-head.txt — начало источника;
• outline-tail.txt — конец источника;
• outline-candidates.txt — до 100-160 строк, похожих на заголовки или маркеры оглавления.

Модель или субагент должны дописать model_decision: язык, домен, стратегию разметки, шаблоны глав/разделов, исключаемые хвостовые зоны и уверенность. После этого segment_text.py --decision outline-scout.json применит решение локально.

Для EPUB сначала проверь script_observations.epub_toc_items: toc.ncx или nav.xhtml обычно точнее, чем заголовки, восстановленные из текста. Если пункты оглавления выглядят правдоподобно, верни их в model_decision.toc_items. Сегментатор умеет искать такие заголовки с нормализацией неразрывных пробелов и переносов строк.

Процесс

1. Прочитай metadata.json и segments/outline.json.
2. Отметь слабые места извлечения: мало слов, нет оглавления, странные заголовки, пустые сегменты.
3. Для каждого сегмента извлекай только рабочий сигнал:
   • named frameworks;
   • критерии выбора;
   • последовательности действий;
   • ловушки и исключения;
   • термины, без которых материал не применить.
4. Своди дубли: один concept-id может опираться на несколько сегментов.
5. Переписывай в деятельной форме: "используй X, когда Y", "проверь A перед B".
6. Добавляй source pointer сразу, пока контекст сегмента открыт.

Что не делать

• Не генерируй пересказ по главам для публичного вида результата.
• Не копируй длинные предложения, таблицы, код, диаграммы и списки из источника по умолчанию.
• Не сохраняй "интересные цитаты" ради полноты.
• Не делай универсальные советы, которые не опираются на источник.
• Не раздувай SKILL.md; если подробность нужна редко, положи её в references/.

Авторская механика

Используй "карточки применения":

Ситуация -> Признаки -> Принцип источника -> Действие -> Проверка -> Источник

Такой формат делает навык полезным в работе и отделяет его от пересказа книги.

Для технических книг

Сохраняй точные имена команд, API и понятий только когда они нужны для работы. Кодовые примеры лучше превращать в шаблон действий или псевдокод. Дословный листинг оставляй только если пользователь явно просит и источник это разрешает.

Для управленческих и гуманитарных книг

Ищи не сюжет, а различения: какие ситуации автор различает, какие ошибки считает типовыми, какой вопрос задаёт перед решением, что считает плохим успехом.