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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
brainstorm-with-docs	Brainstorm and align on a design, grounded in the project's existing docs and vocabulary. Use when exploring an ambiguous problem — whatever the domain — or when grilling a decision fork (развилка): a fan of options, then convergence. The understanding is the deliverable, recorded in the smallest durable artifact (spec, ADR, runbook, research note, CONTEXT.md). Not for implementation, trivial fixes, or executing an already-approved plan.	[problem-or-topic]	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 change the state of any system until the user has approved a design AND explicitly asked to implement: no code, config, or infrastructure changes; no state-changing commands, refactors, data writes, migrations, or deployments; no invoking an implementation skill; no outward-facing actions other than read-only lookups.

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. One documentation move fires earlier: a NEW glossary term is captured in CONTEXT.md inline during the interview (additive; step 4 owns the rule).

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 problems with an unclear direction — the shape is the trigger, not the domain
• choosing between approaches or grilling a decision fork: one decision at a time, a fan of options before converging
• 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.
• Generate the full fan of options before judging any of it — options of genuinely different kinds, not variations of one idea. Composition and width of the fan live in step 5.
• Be direct. Give a real recommendation; don't hide behind "it depends" when the context supports a call.
• 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, plus docs/agents/*.md if present
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
• direction chosen, not yet built → spec / solution design
• durable, surprising, hard-to-reverse trade-off → ADR
• operational procedure / recovery / diagnostics → runbook
• shared project vocabulary → CONTEXT.md glossary
• product-facing, user-visible behaviour → PRD

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 — don't batch them. Redefining an already-documented term is a vocabulary change: propose it inline, but confirm before writing (see step 6).

When the interview hits a genuine decision fork — a choice that shapes what comes after — resolve it in place rather than deferring it to the end: run a divergence pass on that fork (see step 5), sized to its weight, and wait for the user's reaction before moving on. Invite reactions to the options you'd reject, not just to the favourite: what the user says about a rejected option often sharpens what they actually want.

5. Diverge, then converge

Two passes, kept separate: first generate options without judging them, then evaluate. Mixing generation and evaluation censors unusual options before they're voiced.

Diverge. Restate the user's implicit frame in one sentence — the assumption their question stands on. Then lay out the fan:

• 2-3 genuinely distinct approaches within the frame;
• at least one option that rejects the frame itself;
• the null option — what happens if this isn't done at all.

Size the fan to the decision's weight. For a cheap, reversible choice the list above is enough; for a hard-to-reverse or expensive-to-unwind one, widen it with the toolkit — each technique carries its trigger:

• axis of variation — options all sit on one axis? Name the axis, add an option from a different one.
• archetype stances — fan feels timid or samey? Force an MVP, a robust, and a radical option.
• inversion — one obvious approach dominates? Add its opposite.
• steal from an adjacent domain — problem feels novel? Ask how another field solves it.
• pre-mortem — stakes are high? Assume the favourite failed in six months; add the option you'd wish you'd considered.

Before presenting, self-check: are these different kinds of answer, or variations of one? If variations, generate one more from a different axis.

Converge. For each option: 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. When the fork is resolved, carry the rejected options and the reasons for rejecting them into the resolution record (the spec's alternatives, the ADR's options considered).

6. Confirm direction

Run <self_review> on the artifact plan — the outline and its key content decisions — before proposing it: the checklist works at decision altitude, no full draft needed. If it opens a gap, return to the interview while no file exists yet.

Then confirm the direction before writing or changing durable project documents. 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, sized by the minimum-sufficient rule from <core_rules>. Write the file once, directly — the plan passed review at step 6, so no draft pass through the chat.

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.

After writing, re-read the written file end-to-end as its reader, not its author — a hot review: the reviewer carries the author's full context, which makes it cheap, and shares the author's blind spots, which is its limit. React by the level of what you find. Text-level defects — wording, structure drift, template mismatches — fix in place, silently. A decision-level find — a contradiction with existing docs or between the artifact's own sections, a hole in coverage, an unhandled scenario — present to the user instead: neither fix it silently nor suppress it. Reopening a decision is the user's call. This re-read is cheap and regularly catches both kinds.

A cold review — a fresh agent with no shared context — inverts that trade: it reads the artifact and the repository, never the conversation, so it is strong on facts and contradictions and weak on fit — on proportion, on what belongs here, and on what the user already settled. Its findings are evidence, not orders: verify each against the artifact and the repo, then dispose of it by the same split as above. Rejecting a finding is a normal outcome. A finding that argues against something the user settled in conversation is a reviewer working without that turn, not a defect — report the argument as a decision-level find. A pass where you rejected nothing is a reason to re-read what you took on trust.

Then go to <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.

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>

A review of the artifact plan — the outline and its key content decisions — run at step 6, before any file is written, so a gap sends the run back to the interview while nothing sits half-baked on disk. Distinct from a spec's ## Validation section, which lists acceptance criteria for the implementation.

Check the plan 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 — the <hard_gate> holds until the user explicitly asks to implement. Offer a small set of next actions, such as:

• refine the spec
• create or update an ADR
• update CONTEXT.md
• create a runbook
• hand the artifact to a cold review — a fresh session or agent with no shared context — where the stakes warrant an independent eye
• derive a compact implementation checklist
• start implementation (only on explicit request)

Do not proceed automatically.

</stop_condition>