brainstorming

name	brainstorming
description	Use when the user says "add X", "build X", "fix X", "change X", "I want to", or otherwise requests any feature, bug fix, or behavior modification, and requirements have not yet been settled in conversation — explores intent and scope with the user before any spec is written.
metadata	{"tags":["tech:markdown","spec-driven","workflow","brainstorming"]}

Brainstorming

Overview

Brainstorming refines a raw request into explicit, settled requirements before any spec file, delta, or code is written. It is a thinking stage conducted in conversation with the user. It produces no file — its output is shared understanding.

Violating the letter of the rules is violating the spirit of the rules.

Do NOT write code, scaffold files, edit existing specs, or draft delta spec content during brainstorming. This skill produces no file. No implementation action until requirements are settled and the user has confirmed (e.g., "ok, write the spec") that `writing-specs` may begin.

The Iron Law

NO SPEC WITHOUT EXPLORED REQUIREMENTS FIRST

When to Use

Always:

• The user describes a new feature, change, or bug fix.
• A previously-closed change needs revisiting.
• You are uncertain whether scope is well-bounded.

Exceptions (ask your human partner):

• Pure documentation typo fixes.
• Refactors with zero behavior change and no spec coverage.

Process

1. Pick a change name. Short, kebab-case, imperative (e.g. add-session-timeout). You will create docs/specs/changes/{name}/ in the next stage; no folder is created yet.
2. Explore context. Read relevant stable specs under docs/specs/{domain}/spec.md. Note existing requirements the change touches.
3. Ask clarifying questions one at a time. Do not batch. Wait for each answer before the next question.
4. Propose 2-3 approaches with trade-offs and a recommended option.
5. Confirm settled understanding with the user in chat: problem, success criteria, out-of-scope, chosen approach, open questions (resolved or deferred).
6. Receive explicit handoff signal from the user — a clear "proceed to spec" / "write it up" / equivalent. Do not infer approval from silence.
7. Hand off. Transition to writing-specs.

Checklist

You MUST work through each of these items and complete them in order:

1. Change name chosen.
2. Existing related stable specs read and noted.
3. Clarifying questions asked one at a time.
4. 2-3 approaches presented with trade-offs.
5. Settled understanding confirmed in chat (problem, success criteria, out-of-scope, chosen approach).
6. User has given an explicit "proceed to spec" signal.
7. Handoff announced to writing-specs.

Common Rationalizations

Excuse	Reality
"This is obviously a small change, skip brainstorming"	Simple changes carry the most unexamined assumptions. The conversation can be short, but MUST happen.
"I already know what the user wants"	Knowing is different from confirmed understanding. Agents misread intent constantly.
"I'll draft the delta first and clarify inline"	Drafting a delta is a writing-specs action. It presumes requirements are settled.
"Let me just start implementing to see what shakes out"	That is the failure mode this skill exists to prevent.
"The user told me exactly what to build"	Fine — confirm success criteria and out-of-scope and still get the explicit proceed signal.

Red Flags — STOP and Start Over

• "The requirements are obvious"
• "Let me just sketch some code first"
• "User said 'whatever you think' — I'll decide"
• Caught yourself asking multiple questions in one message
• Jumped into writing-specs without an explicit proceed signal

All of these mean: stop, resume the conversation, finish the checklist.

Anti-Pattern: "This change is too simple to need a spec"

Every change goes through brainstorming. A config tweak, a one-line bug fix, a copy change — all of them. Simple changes are where unexamined assumptions hide. The conversation can be a few exchanges for a truly small change, but it MUST happen and the user MUST give a proceed signal before writing-specs begins.

Example

User: "Add a 2FA option for admins."

Agent invokes brainstorming. Reads docs/specs/auth/spec.md. Asks: "Which 2FA methods — TOTP, hardware key, both?" Waits. User: "TOTP only." Agent: "Is 2FA required for all admins, or opt-in?" Waits. User: "Required." Agent proposes three approaches (third-party TOTP service vs. in-house vs. hybrid), recommends one, summarizes success criteria + out-of-scope + chosen approach in chat. User: "ok, write the spec." Agent hands off to writing-specs.

Verification Checklist

• Related stable specs read
• Success criteria are concrete
• Out-of-scope items explicitly called out
• Open questions resolved or flagged
• User has given explicit "proceed to spec" signal

Can't check all boxes? You skipped brainstorming. Resume the conversation.

Integration

Terminal state is invoking writing-specs. Do NOT invoke review-changes, plan-review, execution, or any implementation skill.

REQUIRED SUB-SKILL: Use writing-specs after the user gives the proceed signal.