skills/skills/mappa-brainstorm-promote/SKILL.md

name, author, version, description

name	author	version	description
mappa-brainstorm-promote	ours	1.9.0	Finalize a brainstorm buffer (mappa type=brainstorm, status=buffer): two paths. (1) Promote a matured buffer — read → target → brainstorm_promote (atomic buffer → wiki-page + archive, decision 7) → action-items as tasks (task_create, bodies carry brainstorm:N) → review umbrella → covering letter → final entry. (2) Close an already-completed buffer (work done, no wiki needed) — verify linked tasks done → final entry + status=archive. Buffer done ⇔ all action-items created AND all tasks done (incl. review-umbrella) — wiki concepts/buffer-completion-criteria. General mappa mechanism. Old name — trigger-synonym: workshop-promote-brainstorm. Triggers (bilingual): «промоутни брейнсторм», «выкати в вики», "promote the brainstorm", "finalize <topic>", "publish to wiki"; «закрой буфер», «архивируй буфер», "close the buffer", "archive the buffer".

mappa-brainstorm-promote

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.

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

Completion criteria (wiki concepts/buffer-completion-criteria, .workshop): a buffer is done ⇔ (all action-items are created as tasks) ∧ (all created tasks are done, including the review-umbrella). Two entry paths to archive:

• Promote (steps 5–9): a maturing buffer whose content must land in a wiki — brainstorm_promote (wiki page + archive atomically).
• Close (step 5b): an already-completed buffer — work done long ago (tasks done / resolved / legacy-promoted in the file era), no wiki page needed. Verify the chain — in the graph for same-project links, via direct task_get for cross-project tasks — write the final entry, brainstorm_update(status='archive'). This is how done-but-not-closed buffers are swept (case: entity-uuid brainstorm:109, tasks 1067/1068/1093 done, buffer still buffer with zero edges — audit 2026-08-25).

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

• «промоутни брейнсторм», «выкати в вики», "promote the brainstorm", "finalize ", "publish to wiki".
• The user references a brainstorm entity (brainstorm:N) or a buffer topic that matured and is ready for promotion.

Inputs

• 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 entity in mappa (type=brainstorm, status=buffer)
        │
        ▼
   find + read (entity_search type=brainstorm → entity_get full body)
        │
        ▼
   ask: target project (where to promote)
        │
        ├── close (no promotion): work already done, no wiki page needed
        │     → step 5b (graph check + final entry + status=archive)
        │
        ├── ordinary project → brainstorm_promote(project=<target>)
        │                    → wiki page (spec) in the target wiki
        │
        └── skill → dialog: description (trigger contract)
                    → preview + confirm
                    → mkdir + Write SKILL.md (skeleton) in ~/projects/skills/
                    → git add + commit (local, no push/install)
        │
        ▼
   parse action-items from the buffer body
        │
        ▼
   for each: mcp__mappa__task_create (SEQUENTIALLY, not batched)
        │
        ▼
   review-umbrella: mcp__mappa__task_create (blocked, blocker=impl#)
        │
        ▼
   covering letter: mcp__mappa__inbox_send (mappa-delegation canon)
        │
        ▼
   final report (wiki:NNNN — spec, brainstorm:N — archive, tasks)

Steps

1. Find the buffer in mappa. mcp__mappa__entity_search(type='brainstorm', project=<project>, q=<topic>) → in the results brainstorm:N (ref). Read the full buffer: mcp__mappa__entity_get(key) — key = uuid or full ref brainstorm:N (task:1067; bare numbers → 400) — body = running record (frontmatter + rounds). The response carries the internal id for brainstorm_promote.

   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. Show the buffer summary (≤2 paragraphs).

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=). If not — abort with a message.

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-]+).
   • 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. Content promotion (always via brainstorm_promote, decision 7):

   mcp__mappa__brainstorm_promote(project=<target>, brainstorm_id=<internal id>)

   • 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.

5b. Closing an already-completed buffer (no promotion). When the work is already done and no wiki page is needed (legacy-promoted, resolved by the human, tasks all done, or the decision was reversed):

• Verify the chain: mcp__mappa__graph_neighbors/graph_backlinks on the buffer for same-project links (edges resolve in the owner's project scope, finding #1014); for cross-project tasks (workshop → target, the normal case) resolve the refs from the body/final entry via direct mcp__mappa__task_get(task:N) — every linked task must be status=done (or the buffer is closed by content: «решено»/«отменено»). If tasks are done but nothing is written — the chain was never recorded; the final entry below fixes it (backward text refs).
• Append the final entry to the body via mcp__mappa__brainstorm_update (body, expected version; 409 → re-GET → retry): «Закрытие (дата) — цепочка завершена: task:N… done / решено / промоутнуто (легаси). Критерий: concepts/buffer-completion-criteria». The [[task:N]] and [[wiki:…]] links create the closing edges on write (decision 4).
• Set status='archive' in the same brainstorm_update. Buffer archived without a wiki page — the knowledge is already where it belongs or is historical (review reports, legacy plans).
• Report: brainstorm:N → archive, with the reason.

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. Task creation:

   NB: create tasks SEQUENTIALLY, not batched. One task_create → wait for the response → the next one.

   • Ordinary target: for each action-item — mcp__mappa__task_create(project=<target>, slug=<kebab>, title, description, status='ready'). Create — carve-out, no lease needed (wiki:2660/#1054). The impl task description references the spec (wiki:NNNN from step 5) and MUST start with the buffer wikilink [[brainstorm:N]] — a ref edge is created on write (decision 4) when the buffer is in the same project as the task; cross-project it stays a searchable text ref (entity_search "brainstorm:N" finds the task).
   • 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>-.
   • 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 (for a target with impl tasks, and for skill — always):

   mcp__mappa__task_create(project=<target>, slug=<topic>-review, 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. 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).

8b. Final entry in the buffer (closing the chain). After tasks are created, append to the buffer body via mcp__mappa__brainstorm_update (body + expected version; 409 → re-GET → retry): «Промоут → wiki:NNNN · таски task:N… · review-зонт task:M». This writes the backward refs — the completion record per concepts/buffer-completion-criteria (cross-project: text refs, verified by task_get; same-project: edges). If the body PATCH on an archived entity is rejected — report to the user (the chain stays visible through the tasks' brainstorm:N forward refs).

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=<your folder>, subject='Promotion <topic>: tasks <#N…>', body=<list + wiki:NNNN spec>)

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

• 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).
• Closing (step 5b): buffer still has open linked tasks → abort, don't close; report which tasks are open. Buffer is a living storm → abort (close only completed or reversed buffers).
• Closing: brainstorm_update 409 (version) → re-GET → retry; repeated failure → report, buffer stays in buffer.
• 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

• Always: brainstorm_promote — atomically wiki page in the target + buffer → archive + parent_of edges (wiki→buffer, refs→buffer) + brainstorm.promoted event.
• Closing (5b): brainstorm_update — final entry with [[task:N]]/ [[wiki:…]] refs + status → archive; closing edges on write.
• 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

• 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 close a living buffer (5b) — closing is only for completed/reversed work; verify linked tasks via the graph first.
• Don't close without the final entry — the backward refs are the chain.
• Don't invent wiki pages when closing (5b) — closing ≠ promotion.
• 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).