diff --git a/README.md b/README.md index 7fe695c..918a316 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,7 @@ an explicit `adapted-from` marker in its frontmatter. | `find-skills` | `adapted-from: vercel-labs/skills @ c6f69c6` (MIT) — vendored copy | | `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — family collapsed to one skill (pi hides `disable-model-invocation` wrappers) | | `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — divergent phase, visual-companion dropped | +| `mappa-vitya-brainstorming` | `author: ours` — brainstorm METHODOLOGY for a mappa zone (capture in mappa entity, maturity by criterion, spec → wiki, paired+umbrella review, ask who implements, notify); promotion mechanics delegated to `mappa-brainstorm-promote` | | `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 concepts (Iron Law, red flags) | | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate | | `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents | diff --git a/dist/mappa-vitya-brainstorming.skill b/dist/mappa-vitya-brainstorming.skill new file mode 100644 index 0000000..5fb93e4 Binary files /dev/null and b/dist/mappa-vitya-brainstorming.skill differ diff --git a/skills/mappa-vitya-brainstorming/SKILL.md b/skills/mappa-vitya-brainstorming/SKILL.md new file mode 100644 index 0000000..09c7820 --- /dev/null +++ b/skills/mappa-vitya-brainstorming/SKILL.md @@ -0,0 +1,163 @@ +--- +name: mappa-vitya-brainstorming +author: ours +version: 0.1.0 +description: > + The brainstorm METHODOLOGY (the behavior layer) for a mappa knowledge zone — + runs a storm, keeps its running-record buffer, judges MATURITY, and routes + the matured result (spec → wiki concept, tasks, reviews). The mappa promotion + MECHANICS are delegated to mappa-brainstorm-promote. Use when the user opens + a brainstorm or asks whether a storm is mature enough to persist. Triggers: + «забрендшторми», «поштормим», «накидай идеи», «что думаешь про идею», + «разложи куда что», «когда шторм зрелый», "brainstorm this", + "help me think this through", "run the storm". NOT for: sharpening a finished + plan (→ grilling), a single recommendation (→ recommend-dont-menu), or the + mappa promotion mechanics (→ mappa-brainstorm-promote). +--- + +# mappa-vitya-brainstorming + +**This is the vitya-flavored brainstorm *methodology*.** It tells you how to +run a storm in a mappa zone and where the matured output goes. It does NOT +implement the mappa promotion mechanics — that is `mappa-brainstorm-promote`. + +Run a brainstorm **anywhere**, in **any project**, by **any agent**. This is not +boss-zone-only. You (the agent driving the storm) own the method; promotion is +a separate mechanical step you delegate to the promote skill. + +A storm produces impl tasks → this skill also covers the review routing. A +storm that produces **zero impl tasks** (a research/decision-only storm) is +mature when the decisions are distilled into a wiki concept and no review +umbrella is created — the criterion holds vacuously, no tasks to review. + +**Boundary with the promote skill:** this skill ends at "I have judged +maturity and know the routing shape — which decisions become a spec, which +become tasks, how many reviews". It passes a **routing decision** to +`mappa-brainstorm-promote`, NOT a question of whether to persist. + +## When to use + +- User opens a brainstorm: «забрендшторми», «накидай идеи», «что думаешь про + идею», «поштормим», "brainstorm this", "run the storm". +- A storm is running and you must decide whether it's mature enough to persist. +- You must route the matured result into mappa (spec → wiki, tasks + reviews). + +**NOT for:** sharpening a finished plan (→ grilling), single recommendation +(→ recommend-dont-menu), or the actual mappa promotion mechanics (→ +`mappa-brainstorm-promote`). + +## Quick reference + +| Decision | Answer | +|---|---| +| Where does the buffer live | A mappa `brainstorm` entity (status=buffer). NOT a file. | +| When is a storm mature | The buffer-completion criterion, NOT a gut feel. | +| Where does the spec/decisions go | A mappa **wiki concept**. Before any wiki work — run `mappa-knowledge` first. | +| Multiple impl tasks | Paired `-review` per impl + an umbrella `-review`. Both blocked, non-implementer. | +| Who implements | ASK who implements (you are not automatically it). Boss does not implement (Rule 10). | +| Who notifies | Send an `inbox_send` letter to every affected project. | +| Zero-impl storm | Mature when decisions are distilled into a wiki concept; NO review umbrella (criterion holds vacuously). | + +## Core method + +**1. Capture the buffer in mappa, not in a file.** +Start the storm as a mappa `brainstorm` entity (status=buffer). It is the +running record. Update it after each significant decision, not in batches — a +crash-safe append beats token savings. File-based buffers (`.brainstorm/`, +`notes/*.md`) are legacy; the file channel is closed. + +**2. Maturity is a criterion, not a feeling.** +Do not persist on "it feels done". The storm is mature to persist when the +buffer-completion criterion holds: all action-items have been raised as tasks, +and all those tasks are done (including the review-umbrella). Decide this from +the criterion — derived from the graph, not judged by hand. + +**3. Distill into decisions, keep the record.** +The buffer records **decisions** (what was decided and why), not just "we +talked". Refs (`[[...]]`) link entities. The value is the decision trail, not +prose volume. + +**4. Specs/knowledge → mappa wiki concepts.** +Matured conclusions (the "what we decided and why") become a **mappa wiki +concept** (`wiki_create`). It is a formal enough spec: context → decisions → +rationale → non-goals → open questions, so intent is recoverable and tasks can +reference it. Domain knowledge goes to the target project's wiki; workshop-meta +to the `.workshop` wiki entity. **Before any wiki work — run `mappa-knowledge` +first** (Rule 6), it loads the project's AGENTS entity and the read/ingest +contract. + +**5. Review is a separate, non-implementer role.** +When multiple implementation tasks come out of the storm, create BOTH: +- a **paired `-review`** per impl task (status=blocked, blocker=impl-ref); +- an **umbrella `-review`** (status=blocked, blocker=impl-slugs). + +Reviewer is the next session in the target, **not the implementer** — this +fights the "I just wrote it" bias. You (the brainstorming agent) generate the +review tasks; you do NOT do the code review yourself. The umbrella review is +done only when its reviewer confirms — the storm is not mature until the +umbrella `-review` is resolved, not merely created. + +**6. Ask who implements. Do not assume it's you.** +Brainstorms run anywhere by any agent. The implementer is not automatically the +storming agent. If the project is the boss zone (`.workshop`), the boss does NOT +implement (Rule 10) — it distills and routes via `task_create` to a target +project. In other projects the storming agent may implement, but ASK rather +than assume. + +**7. Notify affected projects with a letter.** +A task on a board does not ping a live session. After raising tasks, send an +`inbox_send` letter to every affected project (all except yourself — a +self-copy is not a notification). This is the required ping. + +## Where the mappa promotion happens (delegate, don't repeat) + +The **mechanics** — `wiki_create` / `brainstorm_promote`, `task_create`, +creating review pairs/umbrella, sending the covering letter, adding the final +buffer entry — live in **`mappa-brainstorm-promote`**. This skill does NOT +duplicate those steps; it points to the promote skill for the actual +persistence/promotion. + +**Boundary:** you (the brainstorming agent) run the storm and decide maturity +and routing (what becomes a spec, what becomes tasks, how many reviews). The +promote skill executes the mappa write/promotion. + +## Common rationalizations (excuse → reality) + +| Excuse | Reality | +|---|---| +| "I'll just jot notes in a markdown file" | Buffer must be a mappa brainstorm entity; the file channel is closed. | +| "It feels done, let's write it up" | Maturity is the completion criterion, not a feeling. | +| "The spec can live in docs/ for now" | Spec goes to a mappa wiki concept; before wiki — run `mappa-knowledge`. | +| "I'll review my own tasks, then hand to the user" | Review is a separate non-implementer role; paired + umbrella. | +| "I'm the coding agent, I'll just implement it" | Ask who implements; in the boss zone the boss does not implement. | +| "I'll note the impact in the spec, no need to ping" | Notify every affected project with an `inbox_send` letter. | + +## Red flags (all = STOP and re-orient) + +- You created a `.brainstorm/` or `notes/*.md` file instead of a mappa entity. +- You are persisting because "it feels mature", not by the completion criterion. +- You are about to write the spec to a repo file rather than a mappa wiki concept. +- You are reviewing your own implementation (or the user reviewing it) instead + of a separate non-implementer reviewer. +- You assume you are the implementer for a boss-zone storm. +- You are skipping the `inbox_send` notification to affected projects. + +## Out of scope + +- Does NOT stress-test a finished plan (→ grilling). +- Does NOT give a single recommendation (→ recommend-dont-menu). +- Does NOT execute the mappa promotion mechanics (→ `mappa-brainstorm-promote`). +- Does NOT cover code-discipline / git / versions / push (→ `project-discipline` + / `mappa-vitya-project-discipline`). + +## Cross-agent applicability + +Behavior methodology with a mappa-media dependency. The mappa tool names are +concrete (this zone runs on mappa); the METHOD (capture in a durable record, +maturity by criterion, spec to the durable knowledge store, separate reviewer, +ask who implements, notify affected) transfers to any mappa-based zone. On a +non-mappa setup, substitute the corresponding knowledge channels. + +**`mappa-knowledge` is a mandatory precursor before any wiki work** (Rule 6): +it loads the project's AGENTS entity and the read/ingest contract. Never write +a wiki concept without running it first.