/specs.brainstorm

description: "Provides guided brainstorming capability to transform new feature ideas into pure functional specifications. Documentation-only: never implement code changes, bug fixes, or refactors. For fixes or modifications, route to specs.change-spec. Output: docs/specs/[id]/YYYY-MM-DD--feature-name.md"
argument-hint: "[ idea-description ]"
allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, TodoWrite, AskUserQuestion
model: inherit

Brainstorming

Provides guided brainstorming to transform ideas into pure functional specifications (WHAT, not HOW). Focus on business logic, use cases, and acceptance criteria — no code, frameworks, or technical patterns.

Overview

This command produces a **functional specification** — a document that describes WHAT the system should do, without HOW it will be implemented.

The new workflow:

Idea → Scope Assessment → Functional Specification (docs/specs/[id]/) → Architecture & Ontology → Tasks → Implementation → Review → Cleanup → Done
         (Phase 1.5)          (WHAT, not HOW)                             (docs/specs/)               (spec-to-tasks)
                                                                          
If scope is TOO LARGE:
  Idea → Split into Spec A, Spec B, Spec C → Brainstorm each separately → Multiple focused specifications

**Output**: `docs/specs/[id]/YYYY-MM-DD--feature-name.md`

Preferred naming is `YYYY-MM-DD--feature-name.md`. If the spec folder already uses legacy `*-specs.md` files, keep the existing convention instead of mixing both formats.

Where `[id]` is a unique identifier in format `NNN-feature-name` (e.g., `001-hotel-search-aggregation`).

What vs. How

| Aspect | Functional Specification (WHAT) | Technical Design (HOW) | |----------|-------------------------------------|--------------------------------| | Focus | Business rules, user behaviors | Frameworks, patterns, code | | Language | Natural language | Technical terminology | | Examples | "User can reset password via email" | "Use Spring Security with JWT" | | Output | `docs/specs/[id]/` | `docs/plans/` (deprecated) |

Use this command when starting a new feature to define clear functional requirements before any technical decisions.

Usage

/developer-kit-specs:specs.brainstorm [idea-description]

After generating the functional specification, continue with:

/developer-kit-specs:specs.spec-to-tasks docs/specs/[id]/

Arguments

| Argument | Required | Description | |--------------------|----------|--------------------------------------------------| | `idea-description` | No | Description of the idea or feature to brainstorm |

Current Context

The command will automatically gather context information when needed:

• Current git branch and status
• Recent commits and changes
• Available when the repository has history

Argument Details

**idea-description**

• Purpose: Describes the initial idea, feature, or problem to solve
• Format: Free text describing the concept
• Default: If not provided, the command will ask for it interactively
• Examples: "Add user authentication", "Design caching strategy", "Create a specification for subscription billing"
• Non-examples: "Fix this bug", "Modify this existing behavior", "Refactor payment module" → use `specs.change-spec` instead

---

You are helping a developer transform an idea into a fully formed design. Follow a systematic approach: understand the project context, explore the idea through targeted questions, explore existing code, propose alternative approaches, present the design incrementally, generate professional documentation, review the document, and recommend the next development command.

Core Principles

• **Ask only high-signal questions**: Use AskUserQuestion only when the answer materially changes scope, acceptance criteria, or constraints. If the request is already clear, proceed without adding extra checkpoints.
• **Multiple choice preferred**: Easier to answer than open-ended when possible
• **YAGNI ruthlessly**: Remove unnecessary features from all specifications
• **Functional focus ONLY**: Describe WHAT the system should do, never HOW it will be implemented
• **No technical decisions**: Do NOT mention frameworks, libraries, patterns, or code
• **ADR constraint preservation**: When the input is an ADR, RFC, or technical analysis document, the architectural decisions it contains are treated as **immutable constraints** for the functional specification. If the brainstorming process identifies a need to override an ADR decision, the override MUST be explicitly documented in `decision-log.md` with a DEC entry referencing the original ADR.
• **Incremental validation**: Present specification in sections, validate each
• **Professional documentation**: Use specialist agent for high-quality documents
• **Be flexible**: Go back and clarify when something doesn't make sense
• **Use TodoWrite**: Track all progress throughout
• **No time estimates**: DO NOT provide or request time estimates
• **Scope awareness**: Validate idea scope early; if too large, guide user to split into multiple focused specifications
• **Documentation-only boundary**: This command MUST NOT implement, patch, refactor, or modify application/source code. It may only create or update specification artifacts under `docs/specs/` and related spec documentation files.
• **Route fixes and deltas away**: If the user asks to fix a bug, change existing behavior, refactor existing code, or "just make the modification", STOP and route them to `/developer-kit-specs:specs.change-spec` or an implementation/debugging command. Do not perform the change inside brainstorming.

Spec Lifecycle: Deliberate Death

Every specification has a limited lifespan. The spec is a living document that serves its purpose during implementation, but once the feature