mm-handoff — Snapshot for Next claude.ai Chat

Решает проблему: контекст в чате claude.ai заполнен. Дополняет Anthropic Memory структурированным компактным snapshot'ом, который загружается в Project Knowledge.

Memory vs Handoff: Memory (Anthropic, авто) хранит долгосрочные факты о тебе и проекте. Handoff (этот skill, ручной) — свежий контекст за 1-2 недели: что сделано, что в работе, что открыто. Не конкурируют — дополняют.

Когда вызывать

• Автоматически — из /mm-save-session (шаг 5.6) при каждом закрытии сессии, чтобы handoff.md в Project Knowledge claude.ai всегда был свежим. Это основной путь, руками дёргать не надо.
• Вручную (/mm-handoff или /mm next) — когда контекст текущего чата забился, а сессию закрывать рано: обновить handoff, не закрывая сессию.
• Перед стартом нового чата в claude.ai по тому же проекту
• В конце большой вехи (после серии сессий)
• Перед паузой на несколько дней — чтобы вернуться без раскачки

Скелет handoff.md создаётся ещё на /mm-init-project; первый же /mm-save-session заменяет его полноценной версией через этот skill.

Конфиг

Загрузи mm-config.json по алгоритму из <repo>/docs/CONFIG-LOADING.md. Поддержка mm-config.local.json overlay обязательна.

Понадобятся:

• paths.obsidian_projects
• paths.obsidian_sessions
• paths.obsidian_index (INDEX.md)

Процесс

Шаг 1. Определи проект и хранилище Vault

• Прочитай passport.md в текущей cwd. Если нет — спроси: «Для какого проекта handoff? Дай путь.» или «Запустить /mm-init-project сначала?»
• Из паспорта возьми: имя, тип, путь.
• Определи путь базы знаний <vault_root> (определяй по единому алгоритму: (1) из секции ## Obsidian Knowledge Vault в CLAUDE.md со строкой Хранилище знаний: <путь>, если она есть; (2) локальная папка .vault/ в корне проекта; (3) глобальная папка проекта <obsidian_projects>/<name>/ из конфига).

Шаг 2. Собери сводку последних сессий — index-first, тела лениво

Progressive disclosure (достройка существующей 3-слойной структуры mm, не новый механизм). Индекс однострочников уже есть — не вычитывай полные тела сессий ради «Что сделано». Раньше handoff читал 3-5 ПОЛНЫХ тел при каждом вызове; теперь основной источник — дешёвый индекс, а тела открываются лениво. Цель — экономия контекста на «толстых» проектах.

Определи окно: сессии этого проекта за последние 14 дней (по дате в имени файла YYYY-MM-DD-HHMM-slug или mtime).

1. Индекс-слой (дёшево, основной источник для «Что сделано за период»):

• Прочитай <vault_root>/00-home/index.md И/ИЛИ <obsidian_index> (INDEX.md), отфильтровав строки по этому проекту за окно.
• Каждая строка индекса — готовый однострочник сессии (формат - <дата> · **<project>** · [[Sessions/<id>|<тема/что сделано>]] или аналогичный).
• Парсинг ссылки сессии: Парсер должен принимать любые форматы ссылок: [[Sessions/<id>]], [[sessions/<id>]], а также полные или относительные пути вроде [[Projects/<name>/sessions/<id>]] или [[../Projects/<name>/sessions/<id>]]. Всегда бери `<id>` из самого хвоста пути (имя файла без расширения). ID сессии = <id>.
• «Что сделано за период» собирай из этих однострочников, БЕЗ открытия тел.

1. Тело `sessions/<id>.md` (или по пути из ссылки) открывай ЛЕНИВО — точечно по ID, не все подряд — только когда:

• это топ-1 самая свежая сессия (нужны её «Ключевые решения» и «Открытые вопросы» дословно — см. п.3), ИЛИ
• однострочника индекса недостаточно для внятного пункта (пустой / обрезанный / сессии нет в индексе), ИЛИ
• пользователь явно просит детали по конкретному ID/теме.

1. «Ключевые решения» и «Открытые вопросы» — ВСЕГДА полностью, не прятать в индекс:

• Источник: тело топ-1 свежей сессии (её читаем всегда) + <vault_root>/00-home/текущие приоритеты.md + passport §10.
• Если важное решение/вопрос виден в однострочнике более старой сессии — открой её тело, чтобы не потерять. Детали не теряем — только откладываем чтение; тело остаётся каноном и подтягивается по ID/[[ссылке]].

1. No-op на мелких/молодых проектах: если сессий < 3 ИЛИ однострочники по сути равны телам (очень короткие сессии) — ленивость не даёт выигрыша, читай тела как раньше. Не усложняй там, где экономии нет.

1. Fallback (мягкая деградация и защита от сбоев):

• Старые сессии без чистого однострочника в индексе → прочитай тело. Никогда не падай из-за отсутствия/неполноты индекса.
• Защита от падений: генерация handoff НИКОГДА не должна аварийно завершаться из-за ошибок чтения или отсутствия файлов сессий. Если тело последней сессии (или любой другой) прочесть не удалось (например, неверный путь, удален файл, ошибка парсинга), не падай. Вместо этого заполни доступные секции, а в «Точке возврата» (Point of Return) явно укажи: «не удалось прочитать последнюю сессию (проверьте путь/ссылку)» вместо прерывания генерации.

Извлекаемое на сессию (как и раньше): Дата · Что сделано (1-3 пункта) · Ключевые решения · Открытые вопросы — но «Что сделано» теперь преимущественно из индекса, тела — лениво.

Шаг 3. Собери git-контекст (если репо)

git log --oneline --since="14 days ago"
git status --short
git branch --show-current

Из этого: последние ~10 коммитов, текущая ветка, есть ли несохранённые изменения.

Шаг 4. Прочитай текущие приоритеты

<vault_root>/00-home/текущие приоритеты.md — секция «Сейчас» / задачи.

Шаг 5. Прочитай секцию 10 паспорта

«Текущее состояние» + «Открытые вопросы» + «Известные баги».

Шаг 5.5. Собери GSD context (если применимо)

Если в <project_root>/.planning/ (GSD v1 / core) или <project_root>/.gsd/ (v2):

• Из STATE.md — current milestone + current phase + status
• Из ROADMAP.md — позиция (фаза X из Y)
• Из phases/<NN-current>/CONTEXT.md — топ-3 решения текущей фазы
• Из последних 3 phases/<NN>/SUMMARY.md (по mtime) — что было завершено
• Из HANDOFF.json (v1/core) — last position от /gsd-pause-work (или соответствующей gsd-core команды)

Это станет новым блоком в handoff.md (см. ниже формат).

Шаг 5.6. Если установлен context-mode — подсоси Session Guide

Опционально (улучшает handoff если плагин стоит):

• Проверь существование ~/.claude/plugins/marketplaces/context-mode/ — это значит у юзера установлен плагин.
• Если да — context-mode уже хранит структурированные события сессии в SQLite (~/.claude/context-mode/sessions/). Из этих событий можно извлечь топ-15 категорий (file/rule/prompt/decision/error/task/git/env/skill/subagent/intent/data/role/cwd/mcp).
• Если можешь прочитать sqlite3 — извлеки. Иначе — дай юзеру подсказку в финале: «У тебя стоит context-mode. Для расширенного handoff запусти отдельно ctx_insight MCP-tool и скопируй результат вручную в handoff.md».
• НЕ блокируй handoff если context-mode не установлен — это бонус.

Шаг 5.9. Scrub секретов ПЕРЕД записью (канон config/secret-patterns.json)

handoff.md едет в claude.ai Project Knowledge (внешний сервис). Секрет, случайно попавший из сессии/git в выжимку, утечёт наружу. Поэтому собранный текст handoff прогоняется через фильтр до записи в файл.

Прогони весь собранный текст handoff (все секции) через паттерны из канона <repo>/config/secret-patterns.json (пояснение — <repo>/docs/SECRET-PATTERNS.md):

1. Класс A (высокоточные) — маскируй молча, типизированным плейсхолдером с сохранением контекста (TELEGRAM_TOKEN=<REDACTED:telegram-token>, Bearer <REDACTED:jwt> и т.п. — см. doc). Не вырезай строку.
2. Класс B (широкое `[A-Za-z0-9_\-]{32,}`) — НЕ маскируй (это задевает git SHA-40 / UUID, которых полно в сессиях). Только добавь одну строку-warn пользователю в финальный отчёт: «возможный секрет/длинная строка в <секция> — проверь вручную».
3. Если хоть что-то из Класса A замаскировано — уведоми пользователя одной строкой: что и сколько (🔒 Замаскировано N секрет(ов) в handoff: telegram-token×1, jwt×1).
4. Записывай в handoff.md уже очищенный текст.

Шаг 6. Сгенерируй handoff.md

Сохрани в <vault_root>/handoff.md (перезаписать если есть) очищенный на Шаге 5.9 текст. Формат:

---
project: <name>
generated: <YYYY-MM-DDTHH:MM>
covers_period: <date_first_session> — <today>
sessions_summarized: <N>
---

# Handoff: <name>

> Этот файл загружается в Project Knowledge чата claude.ai вместе с passport.md.
> Цель — новый чат должен быть в курсе **последних 1-2 недель работы** без чтения всех сессий.

## Сейчас в работе

<2-3 строки из dashboard.md секции "Сейчас" + git status>

Ветка: `<branch>` | Несохранённые изменения: <N файлов / нет>
Последний коммит: `<hash> <date> <subject>`

<!-- Structured snapshot — 15 категорий вдохновлено context-mode Session Guide -->
## Структурированный snapshot

> Краткая сводка по 15 семантическим категориям. Заполняй ТОЛЬКО непустые — пропускай пустые. Источники: текущая сессия, dashboard, последние сессии, git, GSD, context-mode SQLite (если есть).

| Категория | Содержание |
|---|---|
| **Files (P1)** | Файлы которые трогали / читали (топ-5 по частоте) |
| **Rules (P2)** | Активные правила: passport секция 8 (топ-3), CLAUDE.md mm-system, karpathy-guidelines |
| **Decisions (P2)** | Решения принятые за период (топ-5, overflow → 3) |
| **Tasks** | В работе сейчас + WIP из dashboard «Сейчас» |
| **Errors** | Незакрытые ошибки / проблемы |
| **Git** | Branch, last commit, uncommitted N |
| **Env** | OS, runtime versions, ENV vars (только имена!) |
| **Skills** | mm-* + другие skills которые активно использовались |
| **Subagents** | Делегированная работа (Agent tool calls) |
| **Intent** | Режим сессии: feature / bugfix / research / refactor / setup |
| **Data** | Внешние источники данных, API, файлы данных |
| **Role** | Persona / behavioral directives если задавались |
| **CWD** | Рабочая директория (абсолютный путь) |
| **MCP** | MCP-tools которые активно дёргали (топ-3) |
| **Prompt patterns** | Сохранённые удачные промпты из `<obsidian>/Projects/<name>/prompts/` |

Категории P1/P2 — приоритет для compactor'а (P1 сохраняем всегда, P2 — обрезаем при overflow).

<!-- GSD блок: вставляй ТОЛЬКО если в проекте есть .planning/ или .gsd/ -->
## GSD контекст (если применимо)

- **Версия**: <v1 .planning/ | v2 .gsd/ | core .planning/ config.json>
- **Milestone**: M<N> «<title>», прогресс <X>/<Y> фаз
- **Текущая фаза**: <NN-current> «<title>» — статус <draft | discussed | planned | in-progress | verified | complete>
- **Последние завершённые фазы** (топ-3 по mtime SUMMARY.md):
  - <NN-X> «<title>»: <одна строка из SUMMARY>
  - <NN-Y> «<title>»: <одна строка>
  - <NN-Z> «<title>»: <одна строка>
- **Решения текущей фазы** (из CONTEXT.md):
  - <решение 1>
  - <решение 2>
- **HANDOFF.json** (если есть и свежее): <position + what_next в одной строке>

## Что сделано за период

<Объедини findings из 3-5 сессий в 5-8 буллетов. Группируй по темам, не по датам. Дедуплицируй.>

- <тема>: <что сделано> [[sessions/<file>]]
- <тема>: <что сделано> [[sessions/<file>]]

## Ключевые решения и почему

<Из секций "Ключевые решения" сессий — то что переживёт неделю.>

- **<решение>** — <почему> (сессия [[sessions/<file>]])

## Что НЕ работает / в незаконченном виде

- <bug или WIP> — <статус>

## Открытые вопросы (приоритет ↓)

- [ ] <q1>
- [ ] <q2>

## Следующий логичный шаг

<1-2 предложения. Что взять первым в новом чате.>

## Точка возврата

> Куда именно вернуться в следующей сессии. Источник — секция «Точка возврата» самой свежей сессии (её тело читается всегда, Шаг 2 п.3) + текущий git status (Шаг 3).

- **Следующий конкретный шаг:** <одно действие, с чего начать>
- **Если прервались посреди:**
  - Недоделано: <что осталось в текущем шаге / «—»>
  - Неотправленный промпт: <текст готового, но не выполненного промпта целиком / «нет»>
  - Недокоммиченный WIP: <файлы из git status / «нет, дерево чисто»>

## Где смотреть подробности

- Паспорт: [[atlas/passport]]
- Оглавление: [[00-home/index]]
- Приоритеты: [[00-home/текущие приоритеты]]
- Все сессии: [[sessions/]]
- Код: `<абсолютный путь>`

---

**Для нового чата claude.ai:**
1. Open Project «<name>» (Knowledge содержит этот файл + passport.md)
2. Первой репликой можно сказать: *«Привет. Прочитай handoff.md и passport.md, кратко скажи где мы и предложи следующий шаг.»*

Шаг 7. Обнови оглавление 00-home/index.md

В <vault_root>/00-home/index.md обнови карту заметок, если были добавлены новые решения/баги/паттерны.

Шаг 8. Финальный отчёт

✅ Handoff готов

Файл: <abs_path>/handoff.md
Покрывает: <N сессий> с <date> по сегодня
Открытых вопросов: <K>

Что делать:
1. claude.ai → Project «<name>»
2. Если handoff.md уже был в Knowledge — удали старый, загрузи новый (Anthropic не оверрайдит файлы автоматически)
3. New Chat в этом Project
4. Первая реплика: «Прочитай handoff.md и passport.md, скажи где мы и предложи следующий шаг.»

Edge cases

• Нет сессий за период (< 3 файлов): handoff.md всё равно делай, но в "Что сделано" пиши «Свежий проект, истории нет — см. passport.md».
• Нет 00-home/index.md: создай минимальный.
• Нет паспорта: останови, скажи Сначала /mm-init-project.
• Несколько связанных проектов (моно-репо): handoff делается на конкретный проект (по cwd), пользователь выбирает имя.

Что НЕ делать

• Не пиши handoff длинной более 1.5 страниц. Цель — компактность.
• Не копируй полные тексты сессий. Только выжимки.
• Не выдумывай решения и open questions, если их нет в источниках.
• Не трогай passport.md из этого скилла (для этого есть /mm-init-project в режиме update).