Dmitry DementievandClaude Opus 4.8
6f9de57b0c
- Зачем:
- гравитация скилла тянула к «выдать артефакт»; управляющие документы
раздувались деталями реализации (диагностировано на живом тесте — ADR
с инлайном SQL).
- Что:
- gate/stop: «готово» = общее понимание + рекомендованное направление,
записанное минимально-достаточно, а не «артефакт произведён»; определение
в одном месте (stop_condition), gate на него ссылается.
- core_rules: минимально-достаточный артефакт + барьер высоты (без инлайна
исполняемых артефактов) + single source of truth; приоритет над
конвенциями репозитория.
- шаг 2: артефакт(ы) выбираются ПОСЛЕ понимания, набором по жанрам.
- adr.md/spec.md: Lifetime test → Scope test (ADR↔spec по охвату, не сроку);
detailed plan — transient и вне scope скилла.
- description + README: формулировки-цели ведут пониманием, не артефактом.
- Проверка:
- grep: старый framing (lifetime/transient) убран; cross-ref Scope test
сходится; определение «готово» не дублируется; витрина не artifact-first.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# 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 drives it to shared understanding and a recommended
|
|
direction — recorded in 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 four 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** — comparing 2-3 viable approaches within the user's
|
|
framing, plus at least one framing-challenger so the agent does not only
|
|
optimise inside the first shape of the problem;
|
|
- **durable output** — the understanding is the deliverable; it's recorded in the
|
|
smallest appropriate artifact: glossary entry, spec, ADR, runbook, research
|
|
note, or PRD.
|
|
|
|
The closest day-to-day comparison is `grill-me`: use `grill-me` when you mainly
|
|
want the agent to pull understanding out of you and align on a plan in the
|
|
conversation. Use `brainstorm-with-docs` when the discussion must be grounded in
|
|
the repository and leave behind project documentation. `grill-with-docs` is an
|
|
upstream influence for glossary and ADR discipline, but this skill is not trying
|
|
to follow that methodology wholesale.
|
|
|
|
## 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 discourage that, but the
|
|
description's positive surface is broad (architecture / DevOps / research), so
|
|
expect it to fire more eagerly on Codex than on Claude. If that gets noisy,
|
|
narrow the description.
|
|
|
|
## 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 with an additive framing-challenger, durable
|
|
artifacts, stop-before-implementation.
|
|
- **v2 (planned):** tiered fuller divergence for heavier decisions, an
|
|
idea-generation toolkit, a "design for isolation" lens, and fuller
|
|
multi-context support. A `<!-- SEAM -->` marker in `SKILL.md` step 5 marks where
|
|
it slots in.
|
|
|
|
See [ROADMAP.md](ROADMAP.md) for the full backlog, pending decisions, and what
|
|
has been considered and rejected. `ROADMAP.md` is development memory and can be
|
|
removed once the skill stabilises.
|
|
|
|
## 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. This skill deliberately diverges from
|
|
`grill-with-docs` where the user's workflow needs broader artifact creation and
|
|
option exploration.
|
|
- **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.
|