ddadmin
9d825cfca3
- Зачем: - навык должен автоматически вызываться по описанию, а не только вручную. - Что: - удалена опция disable-model-invocation: true из frontmatter. - Проверка: - git diff — изменения только в SKILL.md.
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 inSKILL.mdstep 5 marks where it slots in.
See 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.mddiscipline, lightweight ADRs, and the active grilling techniques. This skill deliberately diverges fromgrill-with-docswhere 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.