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