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

---
name: brainstorm-with-docs
description: Structured brainstorming and design alignment for unclear technical problems, grounded in the project's existing docs and vocabulary — questioning assumptions, sharpening terminology, comparing options, and reaching shared understanding and a recommended direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem; the understanding is the deliverable, recorded in the smallest durable artifact (spec, ADR, runbook, research note, or CONTEXT.md glossary update). Not for implementation, trivial fixes, or executing an already-approved plan.
disable-model-invocation: true
argument-hint: "[problem-or-topic]"
allowed-tools: Read Grep Glob Write Edit WebSearch WebFetch Bash(git log:*) Bash(git diff:*) Bash(git status:*) Bash(git show:*)
---

# Brainstorm With Docs

Move the user from an unclear problem to shared understanding, clear project
language, viable options, a recommended direction, and the smallest useful
durable documentation artifact. This skill is for thinking, alignment, and
documentation — not for implementation.

<hard_gate>

Do NOT write code, change configuration or infrastructure, run state-changing
commands, refactor, run migrations, deploy, or invoke any implementation skill
until the user has approved a design AND explicitly asked to implement.

Approval of a design direction is NOT approval to implement. The deliverable of
this skill is shared understanding and a recommended direction; the document is
only the smallest record that preserves it, never the goal in itself. (When you
are done, and how to stop, is in `<stop_condition>`.)

The skill may freely investigate — read project files, run read-only inspection
commands, and look up external documentation — and may create or update
documentation files once the user agrees on the direction. It must NOT change the
state of any system: no code, config, or infrastructure changes; no data writes
or migrations; no deployments; and no outward-facing actions other than read-only
lookups.

If you are unsure whether a command has side effects — especially when querying a
live or production system — state what you intend to run and why, and get a yes,
before running it. Do not rely on the harness to stop you; in auto mode it may
not.

</hard_gate>

<what_to_do>

Use this skill for:

* ambiguous engineering tasks
* architecture or design decisions
* DevOps and infrastructure work
* research-heavy technical tasks
* migration, integration, or operational-procedure design
* choosing between implementation approaches
* converting a discussion into a durable specification
* clarifying project terminology and assumptions

Do not use this skill for:

* tiny mechanical edits or straightforward bug fixes with an obvious cause
* simple code generation
* pure execution of an already-approved plan
* cases where the user explicitly asks to skip discussion and implement

If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement.

</what_to_do>

<core_rules>

* Ask one question at a time when interviewing; wait for the answer.
* Never ask for something the repository can answer — search first.
* Prefer project-specific language over generic terminology.
* Surface assumptions, constraints, risks, trade-offs, and non-goals.
* Don't interview forever — when the problem, constraints, and success criteria
  are clear enough, stop asking and synthesize.
* Offer 2-3 viable approaches within the user's framing, plus at least one (more
  if useful) that challenges the framing itself — the null option, a reframe, an
  adjacent-domain steal. Without the framing-challenger, options collapse into
  variations of one idea. Don't pad to hit a number; every option must be
  genuinely distinct.
* Be direct. Give a real recommendation; don't hide behind "it depends" when the
  context supports a call.
* Explicitly state what should NOT be done now.
* Minimum-sufficient artifact: the smallest form that *fully* preserves the
  understanding — and no smaller. Sized to the understanding, not "as small as
  possible": a large understanding earns a fuller document, a small one a paragraph.
* Keep documents at decision altitude: record the decision and the understanding
  in prose. Do NOT inline executable artifacts (code, config, DDL, schemas) — name
  the decision and point to the artifact that holds it. Inlining executable detail
  is implementation, even when it looks like "stating the decision precisely".
* Each fact lives in one artifact — cross-reference, never duplicate. Several
  artifacts from one understanding is fine; the same content in several is not.
  These altitude and size rules outrank a heavier local doc style: match the
  repo's section structure, but don't inflate or duplicate to fit it.
* Keep `CONTEXT.md` strictly a glossary; create ADRs only sparingly.
* Do not produce a detailed implementation plan unless the user asks for one.

</core_rules>

<how_to_do_it>

## 1. Inspect project context

Before asking the user anything, read the relevant context. Prefer this order:

1. `AGENTS.md` or an equivalent project map
2. README / project overview
3. `docs/`, then existing specs and design docs
4. ADRs (`docs/adr/`), runbooks, status docs
5. code and config relevant to the problem

Look for: existing terminology, decisions already made, known constraints,
previously rejected options, deployment model, testing/validation conventions,
and patterns the solution should follow. Respect a documented structure if one
exists. If no context is available, say so and continue with what the user gives.

Investigation often needs read-only commands beyond the pre-approved git set —
listing files, inspecting data, querying a dev datastore. That's expected: run
them (they may prompt for approval), since grounding options in real data is this
skill's main strength. Never run state-changing commands (see the gate).

## 2. Note candidate artifacts (don't commit yet)

Understanding leads; the artifact is its crystallization — so don't pick an
artifact to aim at here. Just keep in mind which kinds the understanding might
crystallize into, and commit only at step 6, once you understand the problem. One
understanding may map to several artifacts (e.g. an ADR for a cross-cutting
decision *and* a spec for the shape of the work), each holding a different facet.
The kinds, for reference:

* answer still unknown → [research note](artifacts/research-note.md)
* direction chosen, not yet built → [spec / solution design](artifacts/spec.md)
* durable, surprising, hard-to-reverse trade-off → [ADR](artifacts/adr.md)
* operational procedure / recovery / diagnostics → [runbook](artifacts/runbook.md)
* shared project vocabulary → [`CONTEXT.md` glossary](artifacts/context.md)
* product-facing, user-visible behaviour → [PRD](artifacts/prd.md)

Don't force everything into a PRD. Read an artifact's file only when you're
actually about to write that kind of artifact.

## 3. Check scope and decompose if needed

Before deep brainstorming, check whether this is one coherent problem or several.
If it's too broad, pause and propose a decomposition — separating research from
implementation, design from execution, product requirements from engineering
design, one-time setup from recurring operations, reversible from hard-to-reverse
decisions. Ask which part to handle first.

## 4. Interview / grill

Interview the user until the problem is clear enough to synthesize. One question
at a time. For a decision or choice question, offer your recommended answer and a
one-line why — a concrete recommendation to react to moves the user further than a
bare question; for pure fact-gathering a recommendation may not apply. When the
reason for a question isn't obvious, briefly say why it matters. Prefer questions
that clarify: the actual problem and why it matters,
expected outcome, who is affected, constraints, non-goals, success criteria,
failure modes, operational and security risks, reversibility, deadlines or
sequencing, what's been tried, and what must not change.

Grill actively — don't just collect answers, pressure-test them:

* **Challenge against the glossary.** If a term conflicts with `CONTEXT.md`, call
  it out: "Your glossary defines 'cancellation' as X, but you mean Y — which?"
* **Sharpen fuzzy language.** Propose a precise canonical term for vague or
  overloaded words: "You say 'account' — Customer or User? Those differ."
* **Probe with concrete scenarios.** Invent edge cases that force precision about
  the boundaries between concepts.
* **Cross-reference with code.** When the user states how something works, check
  the code agrees; surface contradictions: "Your code cancels whole Orders, but
  you said partial cancellation is possible — which is right?"

Capture a NEW resolved term in `CONTEXT.md` inline, as it happens (additive, low
risk), using the format in [artifacts/context.md](artifacts/context.md) — don't
batch them. Redefining an already-documented term is a vocabulary change: propose
it inline, but confirm before writing (see step 6).

## 5. Synthesize options

<!-- SEAM: a full divergence phase belongs before this convergence step (v2).
     Rationale, toolkit, and status live in ROADMAP.md — not here, so a running
     agent isn't primed with the design intent. -->

Present 2-3 viable approaches within the user's framing, plus at least one that
challenges it. For each: short description, when it fits, benefits, trade-offs,
risks, operational implications, documentation impact, and what it avoids or
postpones. Then recommend one, explaining why it fits the
constraints, what risks remain, what to validate first, and what to explicitly
not do now.

## 6. Confirm direction

Before writing or changing durable project documents, confirm the direction.
Confirmation can be lightweight, e.g.:

> "I recommend option B. I'd document it as a solution design, add one
> lightweight ADR for the storage-layout decision, and add two terms to
> `CONTEXT.md`. Does that match your intent?"

Don't ask permission for every wording choice, but DO confirm before: creating a
spec, creating an ADR, changing architectural direction, or changing documented
vocabulary.

## 7. Write the artifact

Once the user agrees, create or update the artifact, following the format in the
matching `artifacts/*.md` file. Choose the minimum-sufficient form — the smallest
that fully preserves the understanding, and no smaller.

Where it goes: follow the repo's existing documentation layout if there is one.
Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in
`docs/adr/`, and other artifacts under `docs/` (e.g. `docs/specs/`,
`docs/runbooks/`). If the location isn't obvious, propose a path and confirm it
as part of step 6 rather than guessing. Create directories lazily.

Then go to `<self_review>` and `<stop_condition>`.

</how_to_do_it>

<shared_project_language>

`CONTEXT.md` is only for shared project language: domain terms, project-specific
concepts, preferred names, terms to avoid, and short relationships between
concepts when they clarify language. It is a glossary, not a spec, work log, ADR
store, validation plan, or list of rejected alternatives.

While interviewing, watch for terms that are ambiguous, overloaded, used
inconsistently, or missing from shared docs. If a durable term matters to future
work, propose adding it. Full format and rules: [artifacts/context.md](artifacts/context.md).

If something is a decision → spec or ADR. If it's an operational procedure →
runbook. If it's a validation rule for this work → the spec.

</shared_project_language>

<self_review>

This is a review of the document itself — distinct from a spec's `## Validation`
section, which lists acceptance criteria for the implementation.

Before presenting the final artifact, review it for: unclear terms, missing
constraints, hidden assumptions, contradictions with existing docs, unnecessary
scope expansion, premature implementation detail, missing validation criteria,
decisions that should (or should not) be ADRs, operational steps that should be a
runbook, and context that does (or does not) belong in `CONTEXT.md`.

If it's too large, propose splitting it. If it's too vague, continue the
interview.

</self_review>

<stop_condition>

You are done once the understanding is shared and minimally recorded — not when
an artifact has been produced. Then STOP. Do not start coding, change
infrastructure, alter configuration, or run state-changing commands unless the
user explicitly asks. Offer a small set of next actions, such as:

* refine the spec
* create or update an ADR
* update `CONTEXT.md`
* create a runbook
* derive a compact implementation checklist
* start implementation (only on explicit request)

Do not proceed automatically.

</stop_condition>