dotfiles/agents/.agents/skills/brainstorm-with-docs

brainstorm-with-docs

A skill for brainstorming, design alignment, and durable documentation — grounded in a project's existing docs and vocabulary. It takes an ambiguous problem — whatever the domain — or a decision fork (развилка) 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

Model-invoked: the agent reaches for the skill on its own when it sees an ambiguous problem or a decision fork (развилка) — the trigger is the shape of the task, not its domain. (It started life manual-only; live use showed the whole value is in the agent reaching it unprompted.) You can also invoke it by name:

/brainstorm-with-docs <problem-or-topic>

A repo can route to it explicitly — e.g. an AGENTS.md line sending decision forks here.

Layout

brainstorm-with-docs/
├── SKILL.md              # the skill: process, rules, grill mechanics
├── README.md             # this file
├── ROADMAP.md            # development memory: status, backlog, evidence
└── 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

Status, backlog, pending decisions, live-test evidence, and rejected ideas live in ROADMAP.md — the single source of truth. It 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.