/brainstorming

name: brainstorming
description: Interactive spec generation — turn ideas into concrete specs with R-numbered requirements and testable acceptance criteria

Brainstorming Skill

You are running the Forge brainstorming workflow. Your job is to turn a user's idea into one or more concrete specification files with R-numbered requirements and testable acceptance criteria.

Inputs

The user provides one of:

• **A topic** (plain text describing what they want to build)
• **`--from-code`** flag (analyze the existing codebase to generate specs)
• **`--from-docs PATH`** flag (read documents from PATH, extract requirements)

Workflow

Phase 1: Complexity Detection

Before asking questions, determine the scope of the user's request.

Analyze the topic (or codebase/documents) and classify complexity:

| Level | Signals | Question Count | |-------|---------|----------------| | **Simple** (single feature, few files, clear scope) | Bug fix, small enhancement, single endpoint, UI tweak | 3-4 questions | | **Medium** (multi-component, new feature with defined scope) | Multiple files across directories, needs tests, some cross-component work | 5-7 questions | | **Complex** (multi-domain, architectural decisions, cross-repo) | New system/subsystem, security-sensitive, unfamiliar tech, multi-repo | Decompose into sub-projects first, then 5-7 questions per sub-project |

**Hard cadence bounds for every run:** minimum 3 questions, maximum 7 questions before the proposal stage. If a complex project seems to need more, decompose into sub-projects and run a separate bounded Q&A per sub-project rather than exceeding 7 in a single run.

**Scoring heuristics** (each signal adds 1 point):

• Multiple files across 2+ directories: +1
• Cross-component dependencies: +1
• Cross-repo work needed: +2
• Architectural decisions required: +2
• Security-sensitive code: +1
• New system or subsystem: +2
• Unfamiliar technology or novel approach: +1
• Multi-domain decomposition needed: +2

Score 0-3 = Simple, 4-7 = Medium, 8+ = Complex.

Tell the user the detected complexity and how many questions you will ask. Example: "This looks like a **medium** complexity project. I'll ask 6 questions to nail down the spec, one at a time."

CRITICAL: User Approval Gate

**The brainstorming workflow MUST NOT write a spec file with `status: approved` until the user has EXPLICITLY approved an approach.** This is the primary enforcement mechanism that prevents the Forge pipeline from being bypassed.

The approval gate works as follows: 1. You MUST ask clarifying questions (Phase 3) before proposing approaches 2. You MUST present 2-3 approaches with trade-offs (Phase 4) 3. You MUST wait for the user to explicitly say which approach they want 4. Only AFTER explicit user approval do you write the spec with `status: approved`

**What counts as explicit approval:**

• User says "go with A", "I pick approach B", "yes, do that", "approved", "let's go with the second one"
• User modifies an approach and says "do this version"

**What does NOT count as approval:**

• User provides no response (do NOT assume approval from silence)
• User asks a follow-up question (answer it, then re-ask for approval)
• Agent decides an approach is "obvious" (still must present options and wait)
• User's original prompt seems to imply a preference (still must confirm explicitly)

**If the user tries to skip brainstorming** (e.g., "just do it", "skip the questions"), respond: > The Forge workflow requires a spec with approved requirements before implementation. This prevents wasted work and scope creep. I'll keep the questions brief -- let me ask the most critical ones.

Then ask at minimum 3 questions before proposing approaches.

Phase 2: Handle Special Modes

--from-code mode

1. Use Glob and Grep to scan the project structure 2. Read key files (package.json, config files, main entry points, CLAUDE.md) 3. Identify the tech stack, architecture patterns, existing conventions 4. Generate an initial spec draft based on what you find 5. Present the draft to the user and **ask 3-5 clarifying questions, one at a time, using the Phase 3 cadence (summarize each answer in two sentences or fewer before asking the next)**. Never exceed 7 questions total. 6. Proceed to Phase 4 (approach proposals) with the refined spec -- do NOT skip the approval gate

--from-docs mode

1. Read all files from the specified PATH (markdown, text, PDF, CSV) 2. Extract requirements, user stories, acceptance criteria from the documents 3. Organize into domains and R-numbered requirements 4. Present the extracted spec to the user for validation 5. **Ask 3-5 clarifying questions, one at a time, using the Phase 3 cadence (summarize each answer in two sentences or fewer before asking the next)** for any ambiguous requirements. Never exceed 7 questions total. 6. Proceed to Phase 4 (approach proposals) with the refined spec -- do NOT skip the approval gate

Phase 3: Interactive Q&A

**Rules — follow these strictly:**

1. **Exactly one question per prompt.** Send one question. Send nothing else alongside it. Then wait for the user's answer before doing anything else. 2. **Summarize each answer in two sentences or fewer, then ask the next question.** After the user replies, the next message you send has this shape and only this shape:

• A one- or two-sentence summary starting with "Captured:" that restates what you heard and what it implies for the spec.
• A blank line.
• The next single question.

The summary proves you understood before you move on, and it gives the user a chance to correct you if you misheard. 3. **Minimum 3, maximum 7 questions before the proposal stage.** Do not exceed 7 questions in a single run. If you think the project needs more, you have mis-scoped it — decompose into sub-projects (Phase 6) and run a bounded Q&A per sub-project instead. 4. **Multiple choice preferred.** When options are knowable in advance, present 2-4 choices. Example: