Brainstorming

---
name: brainstorming
description: "Use when executing, coordinating, planning, or reviewing brainstorming agent workflows, cognitive loops, and architecture standards."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - plan-writing
  - fabel-protocol
  - behavioral-modes
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/checklist.js
  - .agent/scripts/verify_all.js
  - .agent/scripts/lint_runner.js
---

# Brainstorming — Socratic Exploration Mastery

## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `brainstorming` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).


## Activation Boundaries
- **Activate when:** Use when executing, coordinating, planning, or reviewing brainstorming agent workflows, cognitive loops, and architecture standards.
- **DO NOT activate when:** The task falls outside the `brainstorming` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


---

## 🛠️ Technical Architecture & Reference Recipes

## Hallucination Traps (Read First)

- ❌ Jumping to implementation during brainstorming -> ✅ Brainstorming is exploration only; no code is written in this phase
- ❌ Presenting only one option -> ✅ Always present 3+ distinct approaches with tradeoffs
- ❌ Assuming the user's first request is their real need -> ✅ Ask 'what problem does this solve for your users?' before generating ideas

---
## 1. The Socratic Protocol (Mandatory Delay)

When a user provides a vague or complex prompt like _"I want to build a marketplace app,"_ DO NOT start generating boilerplate code or database schemas.

**You must act as a Socratic filter.**

1. Acknowledge the ambition of the goal.
2. Provide 3-5 distinct architectural/functional pathways the user could take.
3. Pause execution. Demand the user makes definitive decisions regarding the permutations before proceeding.

### Example Socratic Prompting:

Instead of: _"Here is the React code for your marketplace,"_
Output: _"Before we write the code, we must lock down the payment flow. Do you want to: A) Handle escrow directly (High liability, complex payout logic), B) Use Stripe Connect (Easy routing, strict KYC requirements), or C) Operate free-listing only (Zero liability, requires external monetization)?"_

---

## 2. Multi-Dimensional Tradeoff Analysis

Every design choice has drawbacks. The brainstorming agent must illuminate the implicit consequences of the user's requests.

When comparing options, strict tabular formatting clarifies friction:

| Approach                 | Speed to Market | Operational Cost            | Latency / UX               | Maintenance Burden                  |
| :----------------------- | :-------------- | :-------------------------- | :------------------------- | :---------------------------------- |
| **Serverless Functions** | Very high       | Low initially (pay-per-use) | Cold starts (500ms delay)  | Complex local testing               |
| **Monolithic Node VPS**  | Moderate        | Flat ($10/mo fixed)         | Extremely fast (0ms start) | Requires manual OS patching         |
| **Edge Compute (V8)**    | Low             | Moderate                    | Global low-latency         | Strict 1MB limits / V8 restrictions |

_Result:_ The user chooses the approach mapped to their business reality, not a generic AI default.

---

## 3. Lateral Expansion (The "What If?" Matrix)

Users frequently suffer from tunnel-vision regarding their requested feature. The Brainstormer introduces lateral features the user hasn't considered yet to solidify the schema boundaries.

If user asks for: **"A habit tracking calendar."**
_Expand laterally:_

- "What if a user crosses timezones frequently? Do streaks break?"
- "What if they track binary habits (Read: Yes/No) versus quantitative habits (Drink 6 Liters of water)?"
- "What if they require offline capability while on airplanes?"

---

## 4. Distilling Decisions into Assertions

Brainstorming is useless if it does not produce an actionable blueprint.
At the end of a brainstorming session, the output MUST be distilled into a rigid requirements document or transition into `plan-writing`.

```markdown
# Final Brainstorming Assertions

1. **Architecture:** Next.js SSR Monolith
2. **Database:** Postgres via Prisma (Required for complex relational queries)
3. **Payment:** Stripe Connect (Subverted liability)
4. **Auth:** NextAuth (Google Provider only for MVP)
```

---

## Dynamic Question Generation

**PRINCIPLE:** Questions are not about gathering data—they are about **revealing architectural consequences**.

Every question must connect to a concrete implementation decision that affects cost, complexity, or timeline.

---

### 🧠 Core Principles

#### 1. Questions Reveal Consequences

A good question is not "What color do you want?" but:

```markdown
❌ BAD: "What authentication method?"
✅ GOOD: "Should users sign up with email/password or social login?

Impact:

- Email/Pass → Need password reset, hashing, 2FA infrastructure
- Social → OAuth providers, user profile mapping, less control

Trade-off: Security vs. Development time vs. User friction"
```

#### 2. Context Before Content

First understand **where** this request fits:

| Context                      | Question Focus                                             |
| ---------------------------- | ---------------------------------------------------------- |
| **Greenfield** (new project) | Foundation decisions: stack, hosting, scale                |
| **Feature Addition**         | Integration points, existing patterns, breaking changes    |
| **Refactor**                 | Why refactor? Performance? Maintainability? What's broken? |

#### 3. Minimum Viable Questions

**PRINCIPLE:** Each question must eliminate a fork in the implementation road.

```
Before Question:
├── Path A: Do X (5 min)
├── Path B: Do Y (15 min)
└── Path C: Do Z (1 hour)

After Question:
└── Path Confirmed: Do X (5 min)
```

If a question doesn't reduce implementation paths → **DELETE IT**.

#### 4. Questions Generate Data, Not Assumptions

```markdown
❌ ASSUMPTION: "User probably wants Stripe for payments"
✅ QUESTION: "Which payment provider fits your needs?

Stripe → Best documentation, 2.9% + $0.30, US-centric
LemonSqueezy → Merchant of Record, 5% + $0.50, global taxes
Paddle → Complex pricing, handles EU VAT, enterprise focus"
```

---

### 📋 Question Generation Algorithm

```
INPUT: User request + Context (greenfield/feature/refactor/debug)
│
├── STEP 1: Parse Request
│   ├── Extract domain (ecommerce, auth, realtime, cms, etc.)
│   ├── Extract features (explicit and implied)
│   └── Extract scale indicators (users, data volume, frequency)
│
├── STEP 2: Identify Decision Points
│   ├── What MUST be decided before coding? (blocking)
│   ├── What COULD be decided later? (deferable)
│   └── What has ARCHITECTURAL impact? (high-leverage)
│
├── STEP 3: Generate Questions (Priority Order)
│   ├── P0: Blocking decisions (cannot proceed without answer)
│   ├── P1: High-leverage (affects >30% of implementation)
│   ├── P2: Medium-leverage (affects specific features)
│   └── P3: Nice-to-have (edge cases, optimization)
│
└── STEP 4: Format Each Question
    ├── What: Clear question
    ├── Why: Impact on implementation
    ├── Options: Trade-offs (not just A vs B)
    ├── Fun/Superpower Option: Inject at least one highly creative, unconventional approach
    └── Default: What happens if user doesn't answer
```

---

### 🎯 Domain-Specific Question Banks

#### E-Commerce

| Question                          | Why It Matters                                                     | Trade-offs                         |
| --------------------------------- | ------------------------------------------------------------------ | ---------------------------------- |
| **Single or Multi-vendor?**       | Multi-vendor → Commission logic, vendor dashboards, split payments | +Revenue, -Complexity              |
| **Inventory Tracking?**           | Needs stock tables, reservation logic, low-stock alerts            | +Accuracy, -Development time       |
| **Digital or Physical Products?** | Digital → Download links, no shipping                              | Physical → Shipping APIs, tracking |
| **Subscription or One-time?**     | Subscription → Recurring billing, dunning, proration               | +Revenue, -Complexity              |

#### Authentication

| Question                    | Why It Matters                                       | Trade-offs                   |
| --------------------------- | ---------------------------------------------------- | ---------------------------- |
| **Social Login Needed?**    | OAuth providers vs. password reset infrastructure    | +UX, -Control                |
| **Role-Based Permissions?** | RBAC tables, policy enforcement, admin UI            | +Security, -Development time |
| **2FA Required?**           | TOTP/SMI infrastructure, backup codes, recovery flow | +Security, -UX friction      |
| **Email Verification?**     | Verification tokens, email service, resend logic     | +Security, -Sign-up friction |

#### Real-time

| Question                       | Why It Matters                                                        | Trade-offs                        |
| ------------------------------ | --------------------------------------------------------------------- | --------------------------------- |
| **WebSocket or Polling?**      | WS → Server scaling, connection management                            | Polling → Simpler, higher latency |
| **Expected Concurrent Users?** | <100 → Single server, >1000 → Redis pub/sub, >10k → specialized infra | +Scale, -Complexity               |
| **Message Persistence?**       | History tables, storage costs, pagination                             | +UX, -Storage                     |
| **Ephemeral or Durable?**      | Ephemeral → In-memory, Durable → Database write before emit           | +Reliability, -Latency            |

#### Content/CMS

| Question                    | Why It Matters                              | Trade-offs                    |
| --------------------------- | ------------------------------------------- | ----------------------------- |
| **Rich Text or Markdown?**  | Rich Text → Sanitization, XSS risks         | Markdown → Simple, no WYSIWYG |
| **Draft/Publish Workflow?** | Status field, scheduled jobs, versioning    | +Control, -Complexity         |
| **Media Handling?**         | Upload endpoints, storage, optimization     | +Features, -Development time  |
| **Multi-language?**         | i18n tables, translation UI, fallback logic | +Reach, -Complexity           |

#### Business & Product Strategy

| Question                       | Why It Matters                                  | Trade-offs                  |
| ------------------------------ | ----------------------------------------------- | --------------------------- |
| **Monetization Approach?**     | Freemium vs. Paywall vs. Ads affects user flow  | +Revenue, -User Acquisition |
| **Onboarding CRO?**            | Wizard vs. self-serve dictates state management | +Activation, -Dev Time      |
| **Competitor Differentiator?** | Must highlight this UI feature above all else   | +Standout, -Standardization |
| **Marketing Psychology?**      | FOMO (urgency) vs. Trust (social proof) layout  | +Conversion, -Aesthetics    |

---

### 📐 Dynamic Question Template

```markdown
### 🔴 CRITICAL (Blocking Decisions)

#### 1. **[DECISION POINT]**

**Question:** [Clear, specific question]

**Why This Matters:**

- [Explain architectural consequence]
- [Affects: cost / complexity / timeline / scale]

**Options:**

| Option | Pros        | Cons           | Best For   |
| ------ | ----------- | -------------- | ---------- |
| A      | [Advantage] | [Disadvantage] | [Use case] |
| B      | [Advantage] | [Disadvantage] | [Use case] |

**If Not Specified:** [Default choice + rationale]

---

### 🟡 HIGH-LEVERAGE (Affects Implementation)

#### 2. **[DECISION POINT]**

[Same format]

---

### 🟢 NICE-TO-HAVE (Edge Cases)

#### 3. **[DECISION POINT]**

[Same format]
```

---

### 🔄 Iterative Questioning

#### First Pass (3-5 Questions)

Focus on **blocking decisions**. Don't proceed without answers.

#### Second Pass (After Initial Implementation)

As patterns emerge, ask:

- "This feature implies [X]. Should we handle [edge case] now or defer?"
- "We're using [Pattern A]. Should [Feature B] follow the same pattern?"

#### Third Pass (Optimization)

When functionality works:

- "Performance bottleneck at [X]. Optimize now or acceptable for now?"
- "Refactor [Y] for maintainability or ship as-is?"

---

### 🎭 Example: Full Question Generation

```
USER REQUEST: "Build an Instagram clone"

STEP 1: Parse
├── Domain: Social Media
├── Features: Photo sharing, engagement (likes/comments), user profiles
├── Implied: Feed, following, authentication
└── Scale: Potentially high (social apps go viral)

STEP 2: Decision Points
├── Blocking: Storage strategy, authentication method, feed type
├── High-leverage: Real-time notifications, data model complexity
└── Deferable: Analytics, advanced search, reels/video

STEP 3: Generate Questions (Priority)

P0 (Blocking):
1. Storage Strategy → Affects architecture, cost, speed
2. Feed Algorithm → Affects database queries, complexity
3. Auth Method → Affects dev time, UX, security

P1 (High-leverage):
4. Real-time Notifications → WebSocket vs polling
5. Media Processing → Client-side vs server-side optimization

P2 (Deferable):
6. Story/Reels → Major feature creep, defer to v2
7. DM/Chat → Separate subsystem, defer to v2

STEP 4: Format Output
```

---

### 📊 Generated Output (Example)

```

### 🔴 CRITICAL DECISIONS (Cannot Proceed Without Answers)

#### 1. **Photo Storage Strategy**

**Question:** Where will user photos be stored and served?

**Why This Matters:**
- Affects: Monthly hosting costs, page load speed, CDN complexity
- High-volume social apps: 1000 users × 10 photos × 2MB = 20GB storage

**Options:**
|Option|Cost|Speed|Complexity|Best For|
|--------|------|-------|------------|----------|
|**Cloudinary**|$89/mo (25GB)|Fast (CDN)|Low|MVP, rapid launch|
|**AWS S3 + CloudFront**|$0.023/GB|Fast (CDN)|Medium|Production, cost-optimized|
|**Supabase Storage**|Free tier 1GB|Medium|Low|Small scale, simple|
|**Local Storage**|Server cost|Slow|Low|Development only|

**If Not Specified:** Cloudinary (balanced for MVP)

---

#### 2. **Feed Algorithm Choice**

**Question:** How should the main feed work?

**Why This Matters:**
- Affects: Database query complexity, caching strategy, development time
- Algorithmic feeds require ML infrastructure, ranking signals

**Options:**
|Option|Complexity|Database Impact|Best For|
|--------|------------|-----------------|----------|
|**Chronological**|Low|Simple query|Early stage, transparency|
|**Follow-Only**|Medium|JOIN with pagination|Most social apps|
|**Algorithmic**|High|Pre-computed feed tables|Instagram competitor|

**If Not Specified:** Follow-Only (balanced for social app)

---

#### 3. **Authentication Approach**

**Question:** How do users sign up and login?

**Why This Matters:**
- Affects: Development time (2-5 hours), security posture, UX friction

**Options:**
|Option|Dev Time|Security|UX|Best For|
|--------|----------|----------|-----|----------|
|**Email/Password**|4-5 hrs|High (if 2FA)|Medium|Full control needed|
|**Social Only**|1-2 hrs|Provider-dependent|Smooth|B2C, rapid launch|
|**Magic Link**|2-3 hrs|Medium|Very smooth|Security-focused|
|**Clerk/Auth0**|1 hr|High|Smooth|Fastest to market|

**If Not Specified:** Clerk (fastest for MVP)

---

### 🟡 HIGH-LEVERAGE (Affects Architecture)

#### 4. **Real-time Notifications**

**Question:** Do users need instant notifications for likes/comments?

**Why This Matters:**
- WebSocket adds infrastructure complexity (Redis pub/sub for scaling)
- Polling is simpler but higher latency

**Options:**
|Option|Complexity|Scale Cost|Best For|
|--------|------------|------------|----------|
|**WebSocket + Redis**|High|$10+/mo|>1000 concurrent users|
|**Polling (30s)**|Low|DB queries|<1000 users|
|**No Real-time**|None|None|MVP, validate first|

**If Not Specified:** Polling for MVP (defer WebSocket until validated)

---

### 🟢 NICE-TO-HAVE (Defer to v2)

#### 5. **Video/Reels Support**
- Major complexity (video processing, streaming infrastructure)
- Recommendation: Launch with photos only, add video after validation

#### 6. **Direct Messaging**
- Separate subsystem (chat infrastructure different from feed)
- Recommendation: Use Pusher/Stream for real-time or defer entirely

---

### 📋 Summary

|Decision|Recommendation|If Changed|
|----------|----------------|------------|
|Storage|Cloudinary|+3 hrs setup|
|Feed|Follow-only|+2 hrs query optimization|
|Auth|Clerk|-3 hrs dev time|
|Real-time|Polling|+5 hrs WebSocket setup|
|Video|Defer to v2|N/A|
|DM|Defer to v2|N/A|

**Total Estimated MVP Time:** 15-20 hours with recommendations above
```

---

### 🎯 Principles Recap

1. **Every question = Architectural decision** → Not data gathering
2. **Show trade-offs** → User understands consequences
3. **Prioritize blocking decisions** → Cannot proceed without
4. **Provide defaults** → If user doesn't answer, we proceed anyway
5. **Domain-aware** → Ecommerce questions ≠ Auth questions ≠ Real-time questions
6. **Iterative** → More questions as patterns emerge during implementation

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |


## 🏛️ Tribunal Verification & Guardrails

**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
**Slash Command:** `/review` or `/tribunal-full`

### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.

### ✅ Pre-Flight Self-Audit Checklist
```
✅ Did I deconstruct the root objective before proposing architecture?
✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
✅ Did I avoid over-engineering and select the simplest effective pattern?
✅ Did I verify assumptions with concrete file reads instead of speculation?
✅ Did I establish measurable verification criteria before completion?
```

### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.