brainstorming

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:
3. A one- or two-sentence summary starting with "Captured:" that restates what you heard and what it implies for the spec.
4. A blank line.
5. 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.

1. 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.
2. Multiple choice preferred. When options are knowable in advance, present 2-4 choices. Example:

> How should authentication work? > A) JWT tokens (stateless, good for APIs) > B) Session cookies (simpler, good for web apps) > C) OAuth2 with external provider (Google, GitHub, etc.) > D) Something else (describe)

1. YAGNI ruthlessly. If a feature sounds like premature optimization or speculative, gently push back. "Do you need that for v1, or can we add it later?"
2. Start broad, narrow down. First questions establish scope and architecture. Later questions refine details.
3. Adapt to answers. If the user's answers reveal the project is simpler (or more complex) than initially detected, adjust the remaining question count — but never exceed the hard ceiling of 7.

Correct pattern — one question, then summarize, then next:

Assistant (Q1):

What is the core problem this solves?

User: Our support team has no way to see which customers opened a support email.

Assistant (Q2):

Captured: the goal is tracking email opens for support-sent messages so the team sees who engaged. That implies per-message tracking tied to a customer id.

Who will read this data?

A) Only support agents in their dashboard

B) Support agents plus sales

C) Everyone in the company

D) Something else

Anti-pattern — DO NOT do this:

Assistant (DO NOT do this):

Great idea. To get started, tell me:

1) What is the core problem this solves?

2) Who are the users?

3) What's the tech stack?

4) What are the main features for v1?

5) How should data be stored?

Batching questions lets the user skim or skip. It also wastes context, because the user often answers only the easy ones and leaves the architecturally important ones blank. Always send one question, wait, summarize, then send the next.

Question progression for a typical project (pick the first 3-7 that matter for the detected complexity):

1. What is the core problem this solves? (open-ended)
2. Who are the users? (multiple choice if obvious categories exist)
3. What's the tech stack? (multiple choice based on codebase if detectable)
4. What are the main features for v1? (open-ended, then help them prioritize)
5. How should data be store