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