lucasduys/forge/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:

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.

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 stored? (multiple choice)
6. Are there external integrations? (yes/no, then details)
7. What are the non-functional requirements? (performance, security, scale)

Stop at or before 7. If you still feel blocked on design decisions, that is a signal to propose approaches in Phase 4 with the ambiguity called out as a trade-off, not to keep asking.

For projects with UI components, add a design system question:

Does this project have a design system or brand guidelines?

A) Yes, I have a DESIGN.md file (specify path)

B) I want to base it on an existing brand (e.g., Stripe, Linear, Anthropic, Vercel, Raycast)

C) No specific design requirements -- use sensible defaults

D) I'll provide design specs later

DESIGN.md gate (forge-self-fixes R002). If the user selects option B or names any brand in a free-form answer to this question, you MUST NOT advance to Phase 4 proposal emission until a DESIGN.md exists at the repo root. This gate is enforced by the brainstorm-check-design subcommand:

node scripts/forge-tools.cjs brainstorm-check-design --repo-root <repo> --brand-name <brand>

Exit 0 means the file exists and you may proceed. Exit 3 means it is missing — take one of these paths depending on the brand:

1. If the brand is Anthropic: invoke the brand-guidelines Skill to retrieve the official tokens, write them into DESIGN.md at the repo root using the template at skills/design-system/SKILL.md, then re-run the check.
2. For any other named brand (Linear, Stripe, Vercel, Raycast, etc.): invoke frontend-design and reference the awesome-design-md catalog at https://github.com/VoltAgent/awesome-design-md; write a DESIGN.md derived from whatever reference you can locate.
3. If no brand guide is locatable: ASK the user for a design token source (Figma link, screenshot, or a one-paragraph brand brief) and write DESIGN.md from that before proceeding.

This closes the gap from the 2026-04-21 forge-landing run where the user picked Anthropic aesthetic at Q5 and the brainstorm progressed to Phase 4 without writing any DESIGN.md, causing the executor to approximate brand tokens from memory. The gate is BOTH a documentation rule (bold "MUST NOT" above) AND a programmatic check — if the CLI returns exit 3 and you advance anyway, subsequent Forge audits will catch the violation in state.md decisions.

If option C or D: no DESIGN.md needed, proceed normally. Mark the spec's frontmatter design: key as none (option C) or deferred (option D) so the executor's UI-task routing logic (forge-self-fixes R003) can decide whether to invoke frontend-design anyway.

Phase 3.4: Parallel research dispatch

While the user is still answering questions 3 through 7, the skill should fire forge-researcher subagents in the background so that by the time Phase 4 (approach proposals) starts, 1-2 research artefacts are already on disk and can be cited directly in the trade-off table.

Config gate. Read .forge/config.json. If brainstorm.web_search_enabled is false, skip this entire phase and add a one-line note to the spec's Future Considerations section: Research dispatch disabled (brainstorm.web_search_enabled=false). The default when the flag is missing is true.

When to dispatch.

Do NOT dispatch after questions 5-7; by then you should be converging on the proposal, not widening research.

How to dispatch.