docs(skills): mappa-brainstorm-promote 1.6.0→1.7.0 — English translation, bilingual triggers (task:1086)

This commit is contained in:
2026-08-25 17:42:37 +03:00
parent 195de4b8e6
commit 8cfd46eb09

View File

@@ -1,247 +1,252 @@
---
name: mappa-brainstorm-promote
author: ours
version: 1.6.0
version: 1.7.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>».
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-page in target +
archive, decision 7) → extract action-items into target tasks
(mcp__mappa__task_create, carve-out) → review umbrella → covering letter.
A general mappa mechanism, like task.create/wiki.create — no workshop
specifics. Old name — trigger-synonym: workshop-promote-brainstorm.
Triggers (bilingual): «промоутни брейнсторм», «finalize <topic>», «выкати в
вики», «promote <topic>», "promote the brainstorm", "finalize <topic>".
---
# mappa-brainstorm-promote
Финализация созревшего брейнсторм-буфера, который живёт **как mappa-сущность
типа `brainstorm`** (status=buffer). Это общий механизм mappa — ровно как
`task.create` или `wiki.create`: буфер существует в mappa, скил доводит его до
конца (промоут контента в вики + action-items тасками). Никакой
workshop-специфики: скил триггерится из любой папки, работает с brainstorm-
сущностями любого проекта.
Finalizing a matured brainstorm buffer that lives **as a mappa entity of type
`brainstorm`** (status=buffer). This is a general mappa mechanism — exactly
like `task.create` or `wiki.create`: the buffer exists in mappa, the skill
takes it to the end (promote the content into the wiki + action-items as
tasks). No workshop specifics: the skill triggers from any folder, works with
brainstorm entities of any project.
Процедура линейная (от чтения буфера до промоута и тасок), не цикл: запускается
явно на финальном буфере и доводит его до конца. В форкфлоу встаёт между
работой (`mappa-task-work`) и финишем (`mappa-closing-ritual`).
The procedure is linear (from reading the buffer to promotion and tasks), not
a loop: it's launched explicitly on the final buffer and takes it to the end.
In the forkflow it sits between work (`mappa-task-work`) and finish
(`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; последовательно, не батчем).
**Content promotion — always via `mcp__mappa__brainstorm_promote`:**
atomically creates a wiki page (slug from the buffer, body preserved) in the
project from the call and moves the buffer to `archive` (number/slug stable,
decision 20; parent_of edges, `brainstorm.promoted` event). No file channels.
Action-items go as tasks to the target project via `mcp__mappa__task_create`
(carve-out without a lease, #1054; sequentially, not batched).
## When to use
- «промоутни брейнсторм», «finalize <topic>», «выкати в вики», «promote
<topic>».
- Пользователь ссылается на brainstorm-сущность (brainstorm:N) или на тему
буфера, который созрел и готов к промоушену.
<topic>», "promote the brainstorm".
- The user references a brainstorm entity (brainstorm:N) or a buffer topic
that matured and is ready for promotion.
## Inputs
- Brainstorm-реф `brainstorm:N` или `<topic>` (slug/тема буфера) + project (если
буфер не в текущем проекте — спросить).
- Для skill-ветки дополнительно: `<name>` нового скила (если не указан —
спросить, предложить производное от topic).
- Brainstorm ref `brainstorm:N` or `<topic>` (buffer slug/topic) + project (if
the buffer is not in the current project — ask).
- For the skill branch additionally: `<name>` of the new skill (if not
specified — ask, propose a derivation from the topic).
## Decision flow
```
brainstorm-сущность в mappa (type=brainstorm, status=buffer)
brainstorm entity in mappa (type=brainstorm, status=buffer)
find + read (entity_search type=brainstorm → entity_get полный body)
find + read (entity_search type=brainstorm → entity_get full body)
ask: target project (куда промоутить)
ask: target project (where to promote)
├── обычный проект → brainstorm_promote(project=<target>)
│ → wiki-страница (спека) в вики target
├── ordinary project → brainstorm_promote(project=<target>)
│ → wiki page (spec) in the target wiki
└── skill → dialog: description (trigger contract)
→ preview + confirm
→ mkdir + Write SKILL.md (каркас) в ~/projects/skills/
→ mkdir + Write SKILL.md (skeleton) in ~/projects/skills/
→ git add + commit (local, no push/install)
parse action-items from buffer body
parse action-items from the buffer body
for each: mcp__mappa__task_create (ПОСЛЕДОВАТЕЛЬНО, не батчем)
for each: mcp__mappa__task_create (SEQUENTIALLY, not batched)
review-umbrella: mcp__mappa__task_create (blocked, blocker=impl#)
covering-письмо: mcp__mappa__inbox_send (канон mappa-delegation)
covering letter: mcp__mappa__inbox_send (mappa-delegation canon)
финальный отчёт (wiki:NNNN — спека, brainstorm:N — архив, таски)
final report (wiki:NNNN — spec, brainstorm:N — archive, tasks)
```
## 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 + раунды).
1. **Find the buffer in mappa.** `mcp__mappa__entity_search(type='brainstorm',
project=<project>, q=<topic>)` → in the results brainstorm:N + **internal
id**. Read the full buffer: `mcp__mappa__entity_get(id=<internal id>)` —
body = running record (frontmatter + rounds).
Если буфера нет в mappa — создать brainstorm-сущность через
`mcp__mappa__brainstorm_create` (или HTTP `POST /entities` type=brainstorm,
контракт решения 7/#1054). Не изобретать файловые буферы.
If the buffer is not in mappa — create a brainstorm entity via
`mcp__mappa__brainstorm_create` (or HTTP `POST /entities` type=brainstorm,
contract decision 7/#1054). Don't invent file buffers.
2. **Показать summary буфера (≤2 абзаца).**
2. **Show the buffer summary (≤2 paragraphs).**
3. **Спросить target-проект** — куда промоутить контент. По умолчанию — проект,
где буфер живёт (брейншторм ведут там, где тема релевантна). Проверить, что
проект существует в mappa: `mcp__mappa__entity_search` type=project
(или `mcp__mappa__entity_search` с q=<имя проекта>). Если нет — abort с
сообщением.
3. **Ask the target project** — where to promote the content. Default — the
project where the buffer lives (brainstorms are run where the topic is
relevant). Verify the project exists in mappa:
`mcp__mappa__entity_search` type=project (or `mcp__mappa__entity_search`
with q=<project name>). If not — abort with a message.
4. **Если target = skill (пользователь хочет оформить как скил):**
- Спросить `<name>` нового скила (если не указан) — валидный slug
4. **If target = skill (the user wants it as a skill):**
- Ask `<name>` of the new skill (if not specified) — a valid 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 этого скила).
- Validation (order matters): first check that `~/projects/skills/` itself
is a repository. If not — **abort** with the message "clone skills via
update-skills or manually".
- Then: `~/projects/skills/skills/<name>/` must NOT exist. If it exists —
**abort** with the message "skill `<name>` already exists, update through
the normal route in `~/projects/skills/`, this skill is not for updates".
- Two-pass skeleton: dialog on `description` (activation trigger contract:
minimum 2-3 phrases, Russian/English pairs; what it does; antipatterns) →
preview + confirm → `Write` of the skeleton (header + 6 empty sections) →
local `git commit` in `~/projects/skills/`. **Without** install.sh, push,
build-hermes — those are in the baseline tasks of step 7. The body of the
skeleton is written in a second pass by eye (outside this skill's scope).
5. **Промоут контента (всегда через `brainstorm_promote`, решение 7):**
5. **Content promotion (always via `brainstorm_promote`, decision 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 до создания тасок.
- Atomically: buffer → wiki page (slug from the buffer, body preserved,
parent_of buffer→wiki edges and refs→buffer) + buffer → `archive` +
significant `brainstorm.promoted` event.
- **Frontmatter-summary (wiki:2661):** make sure the buffer body has
`summary:` as one line in the frontmatter — `wiki.search` cards read it.
If missing — append via `mcp__mappa__brainstorm_update` (PATCH
/brainstorm/:id, title/body/status, optimistic version+409) before the
promotion.
- Re-promoting an archived buffer → error (one-shot, idempotent via
status). Cross-check `brainstorm_id` (internal) from step 1.
- If `brainstorm_promote` failed (version conflict, 409) → retry with the
fresh internal id; on a stable failure — abort before creating tasks.
6. **Парсинг action-items:** regex по строкам вида `- [ ] ...` в теле буфера,
секции после `## Следующие шаги`/`## TODO`/`## Next steps`/
`## Action items`. Показать список, дать редактировать/удалять/добавлять.
Если 0 action-items — продолжить, не блокировать.
6. **Action-items parsing:** regex over lines like `- [ ] ...` in the buffer
body, sections after `## Следующие шаги`/`## TODO`/`## Next steps`/
`## Action items`. Show the list, allow editing/removing/adding. If 0
action-items — continue, don't block.
7. **Создание тасок:**
7. **Task creation:**
> **NB:** таски создавать **ПОСЛЕДОВАТЕЛЬНО**, не батчем. Один
> `task_create` → дождаться ответа → следующий.
> **NB:** create tasks **SEQUENTIALLY**, not batched. One `task_create` →
> wait for the response → the next one.
- **Обычный target:** для каждого action-item —
- **Ordinary target:** for each 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'`,
status='ready')`. Create — carve-out, no lease needed (wiki:2660/#1054).
The impl task description references the spec (wiki:NNNN from step 5).
- **Skill:** three baseline tasks in `project='skills'`:
- `[<name>-install]` — run `install.sh` in `~/projects/skills/`,
verify activation in a new session.
- `[<name>-hermes-mapping]` — a record in
`~/projects/skills/hermes/mapping.yaml` (mode `auto` for style ones,
`pending` if it touches tools/environment).
- `[<name>-test-trigger]` — run the trigger phrases from the description:
activates on its own, doesn't activate on 2-3 close foreign ones.
Plus content tasks from the buffer (if any) — also in `project='skills'`,
slug-prefix `<name>-`.
- Если N-я таска упала — продолжить остальные, в конце сообщить какие
созданы / какие нет. Запомнить slug'и для review-umbrella.
- If the N-th task failed — continue the rest, report at the end which were
created / which weren't. Remember the slugs for the review-umbrella.
8. **Review-umbrella (для target с импл-тасками и для skill — всегда):**
8. **Review-umbrella (for a target with impl tasks, and for skill — always):**
`mcp__mappa__task_create(project=<target>, slug=<topic>-review,
status='blocked', blocker=<номера импл-тасок через запятую>, description=<чек-лист>)`
status='blocked', blocker=<impl task numbers separated by commas>, description=<checklist>)`
- **Кто делает:** не имплементер. Следующая сессия в этом проекте (другая
модель / другой день / другой агент) с чистым контекстом. «Я только что
это написал» bias = главный риск.
- Чек-лист: прочитать спеку (wiki:NNNN из шага 5), `git log` shipped-коммитов,
для каждой импл-таски прогнать тесты и сверить с acceptance criteria,
findings → follow-up tasks через `task_create`.
- Закрытие: все findings зафайлены ИЛИ ревьюер подтвердил «нет findings»
в close-note.
- Если review-таска упала — сообщить, **продолжить** к шагу 9 (промоут уже
сделан, буфер в archive).
- **Who does it:** not the implementer. The next session in this project (a
different model / different day / different agent) with a clean context.
The "I just wrote this" bias is the main risk.
- Checklist: read the spec (wiki:NNNN from step 5), `git log` of the
shipped commits, for each impl task run the tests and cross-check with
acceptance criteria, findings → follow-up tasks via `task_create`.
- Closing: all findings filed OR the reviewer confirmed "no findings" in
the close-note.
- If the review task failed — report, **continue** to step 9 (the promotion
is already done, the buffer is in archive).
9. **Covering-письмо в инбокс цели (канон mappa-delegation).** Таска на борде
не пингует живую сессию, письмо = пинг + контекст:
9. **Covering letter to the target's inbox (mappa-delegation canon).** A task
on the board doesn't ping a live session, a letter = ping + context:
`mcp__mappa__inbox_send(project=<target>, from=<своя папка>, subject='Промоушен
<topic>: таски <#N…>', body=<перечень + wiki:NNNN спека>)`
`mcp__mappa__inbox_send(project=<target>, from=<your folder>, subject='Promotion
<topic>: tasks <#N…>', body=<list + wiki:NNNN spec>)`
10. **Финальный отчёт пользователю:**
- Куда промочено: `wiki:NNNN` (спека в вики target).
- Архив: `brainstorm:N` (status=archive, номер стабилен).
- Какие таски созданы (ref, title, проект).
- **Для skill:** напомнить про второй проход «доведём `<name>`».
10. **Final report to the user:**
- Where it was promoted: `wiki:NNNN` (spec in the target wiki).
- Archive: `brainstorm:N` (status=archive, number stable).
- Which tasks were created (ref, title, project).
- **For skill:** remind about the second pass "let's flesh out `<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/` упал → файл остаётся,
сообщить что коммит нужно сделать руками; промоут буфера не блокируется.
- Buffer not found in mappa (no brainstorm entity) → abort, report: create via
`brainstorm_create` (step 1) or HTTP POST /entities.
- `entity_search`/`entity_get` failed (API error, not an empty result) → abort
with the error text; don't create a buffer by guess.
- Target project doesn't exist in mappa → abort before promotion.
- `brainstorm_promote` failed (409 version / stable refusal) → retry with the
fresh internal id; on a repeated failure — abort before creating tasks. The
buffer stays in buffer — retried later.
- Buffer already `archive` (repeated call) → abort: promotion is one-shot,
idempotence via status (decision 7).
- `task_create` failed on the N-th content task → continue the rest, report
partial. The promotion is already done — the buffer is not rolled back.
- `task_create` review-umbrella failed → don't block, report to the user
(create manually from step 8).
- `inbox_send` (covering letter) failed → promotion and tasks are not rolled
back; report to the user, the letter can be sent later (the promotion is
already visible in the graph/inbox of the target).
- **Skill:** `~/projects/skills/` doesn't exist → abort.
- **Skill:** `~/projects/skills/skills/<name>/` already exists → abort.
- **Skill:** user didn't confirm the preview → abort, state unchanged.
- **Skill:** local `git commit` in `~/projects/skills/` failed → the file
stays, report that the commit needs to be done by hand; the buffer promotion
is not blocked.
## 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.
- **Always:** `brainstorm_promote` — atomically wiki page in the target +
buffer → `archive` + parent_of edges (wiki→buffer, refs→buffer) +
`brainstorm.promoted` event.
- **Ordinary target:** spec page in the target project's wiki (with
frontmatter-summary, wiki:2661) + impl tasks + review-umbrella + covering letter.
- **Skill:** skeleton `~/projects/skills/skills/<name>/SKILL.md` (only header +
empty 6-section skeleton) + local commit in `~/projects/skills/`.
**Without** install.sh, push, build-hermes — those are in the baseline tasks.
- Creates N tasks in the target via `mcp__mappa__task_create` (carve-out).
- Creates a review-umbrella task (status=blocked, blocker=impl#).
- Sends a covering letter to the target's inbox.
## 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).
- **Don't use file channels** — the buffer lives in a mappa brainstorm entity,
no `.brainstorm/`/`.archive/` records.
- **Don't use `mcp__projects-meta__tasks_create` / `knowledge_ingest` /
`knowledge_promote`** — file channels are removed. Tasks
`mcp__mappa__task_create`, wiki — `brainstorm_promote` (content) +
`wiki_create`/`wiki_update` (extra pages).
- Don't `git mv` the buffer into the archive — the promotion archives it itself.
- Don't delete the buffer instead of promoting — the graph history is lost
(parent_of, refs).
- Don't batch `task_create` (race; incident 2026-08-24: 6/7 failed) — only
sequentially.
- Don't forget the covering letter — a task on the board doesn't ping a live session.
- **Skill:** don't automatically reformat the buffer body into the skeleton —
the body is written in a second pass by eye.
- **Skill:** don't run `install.sh`, don't push, don't edit
`hermes/mapping.yaml` — those are baseline tasks.
- **Skill:** don't promote into an existing skill (abort).