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