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

name, description, disable-model-invocation, argument-hint, allowed-tools

name	description	disable-model-invocation	argument-hint	allowed-tools
brainstorm-with-docs	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.	true	[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 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
• 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).

5. Synthesize options

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.

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>