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

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 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, 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.

See ROADMAP.md for the full backlog, pending decisions, and what has been considered and rejected. (Dev-phase docs — ROADMAP.md and any DEV-HANDOFF.md — 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.
• 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.