Mm Handoff

---
name: mm-handoff
version: 0.7.0
description: Генерирует handoff.md — компактную сводку для нового чата claude.ai когда контекст текущего заполнился. Включает 15-категорийный Session Guide (вдохновлено context-mode), выжимку последних сессий, текущее состояние, открытые вопросы, и (если есть GSD) — current phase + last 3 SUMMARY.md. Use when user says "контекст заполнен", "новый чат", "handoff", "сводка для нового чата", "/mm-handoff", "пора закругляться, готовь следующий чат". НЕ путать с mm-save-session — этот про подготовку СЛЕДУЮЩЕГО чата, save-session про закрытие текущего.
---

# 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>`.
   - «Что сделано за период» собирай **из этих однострочников**, БЕЗ открытия тел.

2. **Тело `sessions/<id>.md` (или по пути из ссылки) открывай ЛЕНИВО — точечно по ID, не все подряд — только когда:**
   - это **топ-1 самая свежая** сессия (нужны её «Ключевые решения» и «Открытые вопросы» дословно — см. п.3), ИЛИ
   - однострочника индекса **недостаточно** для внятного пункта (пустой / обрезанный / сессии нет в индексе), ИЛИ
   - пользователь явно просит детали по конкретному ID/теме.

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

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

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

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

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

```bash
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 секретов ПЕРЕД записью (по SECRET-PATTERNS.md)

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

Прогони весь собранный текст handoff (все секции) через паттерны из `<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 текст**. Формат:

```markdown
---
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).