feat(skills): добавлен скилл brainstorm-with-docs (v1)

- Зачем:
  - нужен ручной скилл для брейнсторма и дизайна, который удерживает
    словарь смыслов (CONTEXT.md) и лёгкие ADR, активно прожаривает план
    и не сваливается в реализацию.
- Что:
  - SKILL.md: процесс (контекст → классификация → декомпозиция →
    грилл → синтез опций → подтверждение → артефакт), единый HARD-GATE
    «исследуй, но не меняй состояние» с поправкой на auto mode.
  - artifacts/: шаблоны spec, research-note, adr, runbook, prd, context
    (по файлу на тип для progressive disclosure).
  - README.md с MIT-атрибуцией grill-with-docs (Pocock) и brainstorming
    (obra/superpowers); шов для будущей фазы дивергенции в шаге 5.
  - frontmatter переносим: Claude читает все поля, Codex — name+description.
- Проверка:
  - python3 yaml-парс frontmatter; markdown-ссылки на artifacts/ резолвятся.
This commit is contained in:
ddadmin committed 2026-06-02 23:23:41 +03:00
1 parent 0a348da22a
commit 50640d8cb5
8 files changed
+572

No files matched your search

@@ -0,0 +1,81 @@
# brainstorm-with-docs
A manually-invoked skill for **brainstorming, design alignment, and durable
documentation** — grounded in a project's existing docs and vocabulary. It takes
an unclear engineering, DevOps, architecture, migration, integration, research,
or documentation problem and turns it into the *smallest useful* durable
artifact: a spec, ADR, runbook, research note, or `CONTEXT.md` glossary update.
It is deliberately **not** an implementation skill. It reads project files and
proposes documentation, but stops before code, config, or infrastructure changes
— approval of a design direction is never approval to implement.
## Why this exists
It combines three things that are usually separate:
- **shared domain language** (glossary / `CONTEXT.md`) and **lightweight ADRs** —
the discipline of capturing terminology and durable decisions as they crystallise;
- **active grilling** — not just extracting requirements, but pressure-testing
them: challenging terms against the glossary, sharpening fuzzy language, probing
with edge-case scenarios, cross-checking claims against the code;
- **option exploration** — always comparing 2-3 viable approaches with trade-offs
before recommending a direction.
## Usage
Invoke manually:
```
/brainstorm-with-docs <problem-or-topic>
```
On **Claude Code** the skill is manual-only (`disable-model-invocation: true`) —
it never auto-triggers; you always call it. On **Codex** that field is ignored
(Codex reads only `name` + `description`), so it may auto-trigger on matching
design tasks; the negative triggers in the description keep that disciplined.
## Layout
```
brainstorm-with-docs/
├── SKILL.md # the skill: process, rules, grill mechanics
├── README.md # this file
└── artifacts/ # output templates — read only the one you need
├── spec.md # solution design / engineering spec
├── research-note.md # exploratory, answer not yet known
├── adr.md # lightweight architectural decision record
├── runbook.md # operational procedure
├── prd.md # product-facing behaviour
└── context.md # CONTEXT.md glossary format
```
Templates are split per type so the agent loads only what's relevant
(progressive disclosure).
## Roadmap
- **v1 (current):** working hybrid — context inspection, glossary/ADR discipline,
active grilling, option comparison, durable artifacts, stop-before-implementation.
- **v2 (planned):** a *divergence phase* before option synthesis (an
idea-generation toolkit plus the rule "at least one option the user didn't
already imply"), a "design for isolation" lens, and fuller multi-context
support. A `<!-- SEAM -->` marker in `SKILL.md` step 5 marks where it slots in.
## Attribution
This is a derived, original skill — not a copy of either source. It borrows ideas
from two MIT-licensed projects:
- **grill-with-docs / grill-me** by Matt Pocock —
<https://github.com/mattpocock/skills> (MIT, © 2026 Matt Pocock).
Source of the glossary/`CONTEXT.md` discipline, lightweight ADRs, and the
active grilling techniques.
- **brainstorming** by Jesse Vincent (obra), from Superpowers —
<https://github.com/obra/superpowers> (MIT, © 2025 Jesse Vincent).
Source of the explore-context → question → compare-options → present-design flow
and the stop-before-implementation gate.
The `CONTEXT.md` and ADR formats are adapted from Matt Pocock's `grill-with-docs`
companion files. Both upstream projects are MIT-licensed; see their repositories
for full license text.