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 recommending a direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem and turning it into a durable artifact such as a 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. After producing or
updating the agreed documentation artifact, STOP.

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.
* Always consider 2-3 viable approaches before recommending one.
* 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.
* Use the smallest artifact that preserves the useful thinking.
* 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.

## 2. Classify the work and pick the likely artifact

Decide what kind of work this is, then which artifact is likely to fit:

* 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. 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 resolved terms in `CONTEXT.md` inline, as they happen, using the format
in [artifacts/context.md](artifacts/context.md) — don't batch them.

## 5. Synthesize options

<!-- SEAM: v2 will prepend a divergence phase (idea-generation toolkit +
     "at least one option the user didn't already imply") before this
     convergence step. Keep this step self-contained so it can be split. -->

Present 2-3 viable approaches. 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 smallest form that preserves the
thinking.

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 `<validation>` 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>

<validation>

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.

</validation>

<stop_condition>

After the artifact is produced, 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>