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 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.	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. 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
• 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. 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 — don't batch them.

5. Synthesize options

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.

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>

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.

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