brainstorming

Brainstorming

Overview

Purpose: Prevent premature implementation by forcing structured thinking before code. Transform vague requests into concrete, reviewed specifications that the team can confidently build from.

Core principle: Understanding the problem is half the solution. Code written against unclear requirements is rework waiting to happen.

Announce at start: "I'm using the brainstorming skill to explore this properly before we write any code."

When to use

• User brings a new feature idea or significant change
• Architectural decisions with multiple viable paths
• Requirements that feel obvious but have unstated constraints
• Any work where jumping straight to code would risk building the wrong thing

When NOT to use

• Bug fixes with clear reproduction steps (use debugging)
• Trivial changes (typo fixes, config tweaks)
• Work that already has an approved spec

Trigger examples

• "Design how to add real-time notifications, but do not write code yet."
• "We need to decide whether cache is enough here or if we should add Redis."

Workflow

Phase 0: Branch guard (mandatory)

Before doing anything, check the current git branch. If on a baseline branch (main, master, test), create a working branch first:

git checkout -b feature/<slug-from-user-request>

Do NOT brainstorm on a baseline branch. Specs are code — they follow the same branching rules.

Phase 1: Context gathering

Before the steps below: dispatch context-loader with the user's prompt. Use the returned pack (not just docs/_index.md) as the basis for "reading the landscape" below.

1. Read the landscape. Scan relevant existing code, docs, and specs. Understand what already exists before proposing anything new.
2. Identify stakeholders and constraints. Who uses this? What systems does it touch? What are the non-functional requirements (performance, security, accessibility)?
3. Map the edges. What are the boundary conditions, failure modes, and integration points?

Note: docs/inputs/ contains user-provided materials. Only read specific files from it when the user explicitly points you to them.

Phase 2: Socratic questioning

Ask clarifying questions — but ask them well:

• Group related questions (3-5 per round, not 20 in a wall of text)
• Offer options when possible ("Do you need X or Y?" beats "What do you need?")
• Expose hidden assumptions ("You mentioned caching — is the bottleneck actually at the database, or could it be the serialization layer?")
• Stop when diminishing returns — two rounds of questions is typical; three is the maximum before you should have enough to proceed

Phase 3: Approach proposals

Present 2-3 distinct approaches, each with:

Element	What to include
Summary	One sentence: what this approach does
How it works	Key technical decisions, 3-5 bullets
Tradeoffs	Pros and cons, honestly stated
Effort estimate	Relative size (small / medium / large)
Risk	What could go wrong; what is unknown

Do not present a "recommended" option unless the tradeoffs genuinely make one clearly superior. Let the human decide.

Phase 4: Spec writing

Once the user selects or synthesizes an approach:

1. Write the spec to docs/specs/YYYY-MM-DD-<short-slug>.md
2. Include:
   • Goal — what success looks like
   • Chosen approach — the selected option with rationale
   • Scope — what is in, what is explicitly out
   • Technical design — enough detail that a developer can start planning tasks
   • Open questions — anything deferred or needing future resolution
   • Acceptance criteria — concrete, testable conditions for "done"

Phase 5: Gate review

Before the spec is considered approved:

• Submit to the adversarial-document-reviewer gate (see orchestrator-manifest.yaml → agents.gates)
• The reviewer will challenge completeness, internal consistency, and unstated assumptions
• Address feedback or explicitly document why a concern is deferred
• Spec is not approved until it passes the gate

Rules

1. No production code until spec is approved. Prototypes and spikes are fine if labeled as throwaway.
2. Specs live in version control. Same branch rules as code (see skills/git-workflow).
3. Two-way door decisions get less ceremony. If something is easily reversible, the spec can be shorter. If it is a one-way door (database schema, public API, data migration), the spec must be thorough.
4. Kill bad ideas early. If exploration reveals the request is unnecessary, harmful, or already solved — say so. Do not invent work to justify the brainstorming session.
5. Capture rejected alternatives. Future you will wonder "why didn't we just do X?" The spec should answer that.

Anti-patterns

• "Let me just start coding and we'll figure it out" — This is the exact behavior this skill prevents. Resist it.
• Analysis paralysis — Two rounds of questions, 2-3 options, then decide. Do not iterate forever.
• Spec as novel — A spec is a communication tool, not a dissertation. If it exceeds 3 pages, it probably covers too much scope.
• Asking questions you can answer yourself — Read the codebase first. Do not ask the user what framework they use when package.json is right there.
• Single-option "proposals" — Presenting one approach as if there were no alternatives is not brainstorming; it is lobbying.

Integration

Feeds into:

• skills/writing-plans — approved spec becomes input for task decomposition
• skills/git-workflow — spec is committed on a working branch with a draft PR

Gate dependency:

• agents/gates/adversarial-document-reviewer.md — mandatory before spec approval