brainstorming

Forge: Brainstorming

Overview

Help the user explore ideas and approaches before committing to a plan. The output is a structured brainstorm document saved to the session directory.

Do NOT create a plan, write code, or take any implementation action during brainstorming. The ONLY output is the brainstorm document. After brainstorming, the user invokes `forge plan` separately.

Session

Forge sessions are stored in .forge/sessions/<id>/. Multiple sessions let you run several forge workflows in parallel in the same project.

Session Resolution

1. From $ARGUMENTS: If the first token is a number or short identifier (e.g. 1, 42, auth-refactor), use it as the session ID.
2. Auto-detect existing sessions:

   ls .forge/sessions/ 2>/dev/null | sort
   

   • 0 sessions → create a new session (default ID: 1)
   • 1 session → offer to continue it OR start a new one (AskQuestion)
   • 2+ sessions → list them with their brainstorm titles, AskQuestion "Which session, or create a new one?"
3. Creating a new session: auto-increment (max existing numeric ID + 1, or 1 if none). Show the user the assigned ID. Then mkdir -p .forge/sessions/<id>/.

SESSION_DIR = .forge/sessions/<id>/ — all file paths in this skill are relative to this directory.

Process

You MUST follow these steps in order:

0.5. Integration Context (if configured)

Check .forge/config.json:

• If notion key exists → ask: "Soll ich eine existierende Notion-Seite als Input verwenden?" (AskQuestion: "Ja, Notion-Seite lesen" / "Nein, direkt loslegen"). If yes, load notion-sync → Operation C (Pull from Notion) and use content as additional context.
• If linear key exists → ask: "Soll ich offene Linear-Issues als Kontext einlesen?" (AskQuestion: "Ja" / "Nein"). If yes, load linear-sync → list open issues from the project and summarize as additional context.

These prompts are skipped if the user already provided clear input via $ARGUMENTS.

1. Understand the Context

• Read the user's goal/problem description
• Explore the codebase to understand current state:
  • Use the Explore agent (Task tool with subagent_type="Explore") to scan relevant areas
  • Identify existing patterns, architecture, and constraints
  • Find files likely to be affected
• If this is unclear, ask one clarifying question at a time using AskQuestion

1.5. Research (Optional)

After understanding the codebase context, assess whether external research would help:

• Are we working with an unfamiliar library or API?
• Are there known patterns or best practices for this type of problem?
• Do we need to compare approaches that require external knowledge?

If yes, ask the user using AskQuestion:

• Question: "Soll ich vorher recherchieren? (Library-Docs, Best Practices, Patterns)"
• Options: "Ja, recherchiere zu " / "Nein, weiter ohne Research"

If the user says yes:

1. Load and follow the research skill instructions (pass session ID so it writes to the same session)
2. Research findings are saved to $SESSION_DIR/research.md
3. Use the findings to inform the approaches in the next step
4. Reference specific findings when presenting approaches ("Laut der X-Dokumentation...")

2. Explore Approaches

• Generate 2-4 distinct approaches with meaningful trade-offs
• For each approach, cover:
  • What it involves (brief description)
  • Pros and cons
  • Complexity estimate (low / medium / high)
  • Files likely affected
• Present your recommendation first with reasoning
• Use AskQuestion to let the user pick or refine

3. Refine the Chosen Approach

• Once the user picks an approach, dig into details:
  • What's in scope? What's explicitly out?
  • Key technical decisions and their rationale
  • Risks or open questions
• Ask follow-up questions one at a time if needed
• Keep it conversational, not formal

4. Write the Brainstorm Document

Save to $SESSION_DIR/brainstorm.md:

# Brainstorm: <title>

## Goal
<what we're trying to achieve — 1-3 sentences>

## Chosen Approach
<selected approach with rationale — a short paragraph>

## Key Decisions
- <decision>: <choice> — <why>
- <decision>: <choice> — <why>

## Scope
- **IN**: <what's included>
- **OUT**: <what's explicitly excluded>

## Files Likely Affected
- `path/to/file.ts` — <what changes>
- `path/to/other.ts` — <what changes>

## Research (if conducted)
- See `$SESSION_DIR/research.md` for full findings
- <key insight that influenced the chosen approach>

## Risks / Open Questions
- <anything unresolved that planning should address>

Create $SESSION_DIR if it doesn't exist. If $SESSION_DIR/brainstorm.md already exists, ask the user whether to overwrite or append.

4.5. Notion Sync (if configured)

After saving $SESSION_DIR/brainstorm.md, load and follow the notion-sync skill:

• Push the brainstorm to Notion (Operation A: Push Brainstorm)
• This is non-blocking — if Notion sync fails, continue normally

5. Done

Tell the user:

• The brainstorm is saved to $SESSION_DIR/brainstorm.md (session <id>)
• They can run forge plan <id> to create an execution plan from it

Key Principles

• One question at a time — don't overwhelm
• Prefer AskQuestion with options — easier than open-ended when possible
• YAGNI — ruthlessly cut unnecessary scope
• Explore before proposing — read the codebase first, don't guess
• Stay at the idea level — no implementation details, no code snippets