248 lines
17 KiB
Markdown
248 lines
17 KiB
Markdown
---
|
||
name: mappa-brainstorm-promote
|
||
author: ours
|
||
version: 1.6.0
|
||
description: >
|
||
Finalize a matured brainstorm buffer (mappa entity type=brainstorm, status=buffer):
|
||
read buffer → choose target project → promote via mcp__mappa__brainstorm_promote
|
||
(atomic buffer → wiki-страница в target + archive, решение 7) → extract
|
||
action-items into target tasks (mcp__mappa__task_create, карв-аут) → review
|
||
umbrella → covering letter. Общий механизм mappa, как task.create/wiki.create —
|
||
никакой workshop-специфики. Старое имя — триггер-синоним:
|
||
workshop-promote-brainstorm. Triggers (user): «промоутни брейнсторм»,
|
||
«finalize <topic>», «выкати в вики», «promote <topic>».
|
||
---
|
||
|
||
# mappa-brainstorm-promote
|
||
|
||
Финализация созревшего брейнсторм-буфера, который живёт **как mappa-сущность
|
||
типа `brainstorm`** (status=buffer). Это общий механизм mappa — ровно как
|
||
`task.create` или `wiki.create`: буфер существует в mappa, скил доводит его до
|
||
конца (промоут контента в вики + action-items тасками). Никакой
|
||
workshop-специфики: скил триггерится из любой папки, работает с brainstorm-
|
||
сущностями любого проекта.
|
||
|
||
Процедура линейная (от чтения буфера до промоута и тасок), не цикл: запускается
|
||
явно на финальном буфере и доводит его до конца. В форкфлоу встаёт между
|
||
работой (`mappa-task-work`) и финишем (`mappa-closing-ritual`).
|
||
|
||
**Промоут контента — всегда через `mcp__mappa__brainstorm_promote`:**
|
||
атомарно создаёт wiki-страницу (slug из буфера, body сохраняется) в проекте из
|
||
вызова и переводит буфер в `archive` (номер/slug стабильны, решение 20; рёбра
|
||
parent_of, событие `brainstorm.promoted`). Никаких файловых каналов. Action-items
|
||
уходят тасками в target-проект через `mcp__mappa__task_create` (карв-аут без
|
||
лиза, #1054; последовательно, не батчем).
|
||
|
||
## When to use
|
||
|
||
- «промоутни брейнсторм», «finalize <topic>», «выкати в вики», «promote
|
||
<topic>».
|
||
- Пользователь ссылается на brainstorm-сущность (brainstorm:N) или на тему
|
||
буфера, который созрел и готов к промоушену.
|
||
|
||
## Inputs
|
||
|
||
- Brainstorm-реф `brainstorm:N` или `<topic>` (slug/тема буфера) + project (если
|
||
буфер не в текущем проекте — спросить).
|
||
- Для skill-ветки дополнительно: `<name>` нового скила (если не указан —
|
||
спросить, предложить производное от topic).
|
||
|
||
## Decision flow
|
||
|
||
```
|
||
brainstorm-сущность в mappa (type=brainstorm, status=buffer)
|
||
│
|
||
▼
|
||
find + read (entity_search type=brainstorm → entity_get полный body)
|
||
│
|
||
▼
|
||
ask: target project (куда промоутить)
|
||
│
|
||
├── обычный проект → brainstorm_promote(project=<target>)
|
||
│ → wiki-страница (спека) в вики target
|
||
│
|
||
└── skill → dialog: description (trigger contract)
|
||
→ preview + confirm
|
||
→ mkdir + Write SKILL.md (каркас) в ~/projects/skills/
|
||
→ git add + commit (local, no push/install)
|
||
│
|
||
▼
|
||
parse action-items from buffer body
|
||
│
|
||
▼
|
||
for each: mcp__mappa__task_create (ПОСЛЕДОВАТЕЛЬНО, не батчем)
|
||
│
|
||
▼
|
||
review-umbrella: mcp__mappa__task_create (blocked, blocker=impl#)
|
||
│
|
||
▼
|
||
covering-письмо: mcp__mappa__inbox_send (канон mappa-delegation)
|
||
│
|
||
▼
|
||
финальный отчёт (wiki:NNNN — спека, brainstorm:N — архив, таски)
|
||
```
|
||
|
||
## Steps
|
||
|
||
1. **Найти буфер в mappa.** `mcp__mappa__entity_search(type='brainstorm',
|
||
project=<проект>, q=<topic>)` → в результатах brainstorm:N + **internal id**.
|
||
Прочитать полный буфер: `mcp__mappa__entity_get(id=<internal id>)` — тело =
|
||
running record (frontmatter + раунды).
|
||
|
||
Если буфера нет в mappa — создать brainstorm-сущность через
|
||
`mcp__mappa__brainstorm_create` (или HTTP `POST /entities` type=brainstorm,
|
||
контракт решения 7/#1054). Не изобретать файловые буферы.
|
||
|
||
2. **Показать summary буфера (≤2 абзаца).**
|
||
|
||
3. **Спросить target-проект** — куда промоутить контент. По умолчанию — проект,
|
||
где буфер живёт (брейншторм ведут там, где тема релевантна). Проверить, что
|
||
проект существует в mappa: `mcp__mappa__entity_search` type=project
|
||
(или `mcp__mappa__entity_search` с q=<имя проекта>). Если нет — abort с
|
||
сообщением.
|
||
|
||
4. **Если target = skill (пользователь хочет оформить как скил):**
|
||
- Спросить `<name>` нового скила (если не указан) — валидный slug
|
||
(`[a-z0-9-]+`).
|
||
- Валидация (порядок важен): сначала проверить, что `~/projects/skills/`
|
||
сам репозиторий существует. Если нет — **abort** с сообщением «клонируй
|
||
skills через update-skills или вручную».
|
||
- Затем: `~/projects/skills/skills/<name>/` НЕ должна существовать.
|
||
Если существует — **abort** с сообщением «скил `<name>` уже существует,
|
||
обновляйся обычным маршрутом в `~/projects/skills/`, этот скил не для
|
||
апдейтов».
|
||
- Двухпроходной каркас: диалог по `description` (триггер-контракт активации:
|
||
минимум 2-3 фразы, пары русский/английский; что делает; антипаттерны) →
|
||
preview + confirm → `Write` каркаса (шапка + 6 пустых секций) → локальный
|
||
`git commit` в `~/projects/skills/`. **Без** install.sh, push,
|
||
build-hermes — это в baseline-тасках шага 7. Тело каркаса дописывается
|
||
вторым проходом глазами (вне scope этого скила).
|
||
|
||
5. **Промоут контента (всегда через `brainstorm_promote`, решение 7):**
|
||
|
||
`mcp__mappa__brainstorm_promote(project=<target>, brainstorm_id=<internal id>)`
|
||
|
||
- Атомарно: buffer → wiki-страница (slug из буфера, body сохраняется, рёбра
|
||
parent_of buffer→wiki и refs→buffer) + буфер → `archive` + значимое событие
|
||
`brainstorm.promoted`.
|
||
- **Frontmatter-summary (wiki:2661):** убедиться, что в теле буфера есть
|
||
`summary:` одной строкой в frontmatter — карточки `wiki.search` читают его.
|
||
Если нет — дописать через `mcp__mappa__brainstorm_update` (PATCH
|
||
/brainstorm/:id, title/body/status, optimistic version+409) перед промоутом.
|
||
- Повторный промоут архивированного буфера → ошибка (one-shot, идемпотентно
|
||
через статус). Сверить `brainstorm_id` (internal) из шага 1.
|
||
- Если `brainstorm_promote` упал (конфликт версии, 409) → retry со свежим
|
||
internal id; при стабильном отказе — abort до создания тасок.
|
||
|
||
6. **Парсинг action-items:** regex по строкам вида `- [ ] ...` в теле буфера,
|
||
секции после `## Следующие шаги`/`## TODO`/`## Next steps`/
|
||
`## Action items`. Показать список, дать редактировать/удалять/добавлять.
|
||
Если 0 action-items — продолжить, не блокировать.
|
||
|
||
7. **Создание тасок:**
|
||
|
||
> **NB:** таски создавать **ПОСЛЕДОВАТЕЛЬНО**, не батчем. Один
|
||
> `task_create` → дождаться ответа → следующий.
|
||
|
||
- **Обычный target:** для каждого action-item —
|
||
`mcp__mappa__task_create(project=<target>, slug=<kebab>, title, description,
|
||
status='ready')`. Create — карв-аут, лиз не нужен (wiki:2660/#1054).
|
||
Описание импл-таски ссылается на спеку (wiki:NNNN из шага 5).
|
||
- **Skill:** три baseline-таски в `project='skills'`:
|
||
- `[<name>-install]` — запустить `install.sh` в `~/projects/skills/`,
|
||
проверить активацию в новой сессии.
|
||
- `[<name>-hermes-mapping]` — запись в `~/projects/skills/hermes/mapping.yaml`
|
||
(режим `auto` для стилевых, `pending` если трогает тулы/окружение).
|
||
- `[<name>-test-trigger]` — прогнать триггер-фразы из description:
|
||
активируется на своих, не активируется на 2-3 близких чужих.
|
||
Плюс content-таски из буфера (если были) — тоже в `project='skills'`,
|
||
slug-prefix `<name>-`.
|
||
- Если N-я таска упала — продолжить остальные, в конце сообщить какие
|
||
созданы / какие нет. Запомнить slug'и для review-umbrella.
|
||
|
||
8. **Review-umbrella (для target с импл-тасками и для skill — всегда):**
|
||
|
||
`mcp__mappa__task_create(project=<target>, slug=<topic>-review,
|
||
status='blocked', blocker=<номера импл-тасок через запятую>, description=<чек-лист>)`
|
||
|
||
- **Кто делает:** не имплементер. Следующая сессия в этом проекте (другая
|
||
модель / другой день / другой агент) с чистым контекстом. «Я только что
|
||
это написал» bias = главный риск.
|
||
- Чек-лист: прочитать спеку (wiki:NNNN из шага 5), `git log` shipped-коммитов,
|
||
для каждой импл-таски прогнать тесты и сверить с acceptance criteria,
|
||
findings → follow-up tasks через `task_create`.
|
||
- Закрытие: все findings зафайлены ИЛИ ревьюер подтвердил «нет findings»
|
||
в close-note.
|
||
- Если review-таска упала — сообщить, **продолжить** к шагу 9 (промоут уже
|
||
сделан, буфер в archive).
|
||
|
||
9. **Covering-письмо в инбокс цели (канон mappa-delegation).** Таска на борде
|
||
не пингует живую сессию, письмо = пинг + контекст:
|
||
|
||
`mcp__mappa__inbox_send(project=<target>, from=<своя папка>, subject='Промоушен
|
||
<topic>: таски <#N…>', body=<перечень + wiki:NNNN спека>)`
|
||
|
||
10. **Финальный отчёт пользователю:**
|
||
- Куда промочено: `wiki:NNNN` (спека в вики target).
|
||
- Архив: `brainstorm:N` (status=archive, номер стабилен).
|
||
- Какие таски созданы (ref, title, проект).
|
||
- **Для skill:** напомнить про второй проход «доведём `<name>`».
|
||
|
||
## Failure modes
|
||
|
||
- Буфер не найден в mappa (нет brainstorm-сущности) → abort, сообщить: создать
|
||
через `brainstorm_create` (шаг 1) или HTTP POST /entities.
|
||
- `entity_search`/`entity_get` упал (API-ошибка, не пустой результат) → abort
|
||
с текстом ошибки; не создавать буфер по догадке.
|
||
- Target-проект не существует в mappa → abort до промоута.
|
||
- `brainstorm_promote` упал (409 версия / стабильный отказ) → retry со свежим
|
||
internal id; при повторном отказе — abort до создания тасок. Буфер остаётся
|
||
в buffer — ретраится позже.
|
||
- Буфер уже `archive` (повторный вызов) → abort: промоут one-shot,
|
||
идемпотентность через статус (решение 7).
|
||
- `task_create` упал на N-й content-таске → продолжить остальные, сообщить
|
||
partial. Промоут уже сделан — буфер не откатывается.
|
||
- `task_create` review-umbrella упал → не блокировать, сообщить пользователю
|
||
(создать вручную из шага 8).
|
||
- `inbox_send` (covering-письмо) упал → промоут и таски не откатываются;
|
||
сообщить пользователю, письмо можно отправить позже (промоут уже виден
|
||
в графе/инбоксе цели).
|
||
- **Skill:** `~/projects/skills/` не существует → abort.
|
||
- **Skill:** `~/projects/skills/skills/<name>/` уже существует → abort.
|
||
- **Skill:** пользователь не подтвердил preview → abort, состояние не меняется.
|
||
- **Skill:** локальный `git commit` в `~/projects/skills/` упал → файл остаётся,
|
||
сообщить что коммит нужно сделать руками; промоут буфера не блокируется.
|
||
|
||
## Side effects
|
||
|
||
- **Всегда:** `brainstorm_promote` — атомарно wiki-страница в target + буфер →
|
||
`archive` + рёбра parent_of (wiki→buffer, refs→buffer) + событие
|
||
`brainstorm.promoted`.
|
||
- **Обычный target:** спека-страница в вики целевого проекта (с
|
||
frontmatter-summary, wiki:2661) + импл-таски + review-umbrella + covering-письмо.
|
||
- **Skill:** каркас `~/projects/skills/skills/<name>/SKILL.md` (только шапка +
|
||
пустой 6-секционный каркас) + локальный коммит в `~/projects/skills/`.
|
||
**Без** install.sh, push, build-hermes — это в baseline-тасках.
|
||
- Создаёт N тасок в target через `mcp__mappa__task_create` (карв-аут).
|
||
- Создаёт review-umbrella таску (status=blocked, blocker=impl#).
|
||
- Отправляет covering-письмо в инбокс target.
|
||
|
||
## What NOT to do
|
||
|
||
- **Не использовать файловые каналы** — буфер живёт в mappa brainstorm-сущности,
|
||
никаких `.brainstorm/`/`.archive/` записей.
|
||
- **Не использовать `mcp__projects-meta__tasks_create` / `knowledge_ingest` /
|
||
`knowledge_promote`** — файловые каналы выпилены. Таски —
|
||
`mcp__mappa__task_create`, вики — `brainstorm_promote` (контент) +
|
||
`wiki_create`/`wiki_update` (доп. страницы).
|
||
- Не делать `git mv` буфера в архив — промоут архивирует сам.
|
||
- Не удалять буфер вместо промоута — теряется граф-история (parent_of, refs).
|
||
- Не батчить `task_create` (гонка; инцидент 2026-08-24: 6/7 упали) — только
|
||
последовательно.
|
||
- Не забывать covering-письмо — таска на борде не пингует живую сессию.
|
||
- **Skill:** не переформатировать тело буфера в каркас автоматически — тело
|
||
дописывается вторым проходом глазами.
|
||
- **Skill:** не запускать `install.sh`, не делать push, не править
|
||
`hermes/mapping.yaml` — это baseline-таски.
|
||
- **Skill:** не промоутить в существующий скил (abort).
|