| name | brainstorming |
| description | Socratic methodology, ideation, and architectural exploration mastery. Generating extensive feature options, analyzing trade-offs, questioning assumptions, mind-mapping components, and delaying execution. Use when evaluating new features, defining project goals, or guiding users through ambiguous design spaces. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
| version | 3.1.0 |
| last-updated | "2026-04-06T00:00:00.000Z" |
| applies-to-model | gemini-2.5-pro, claude-3-7-sonnet |
| routing | {"domain":"general","tier":"basic"} |
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
Brainstorming — Socratic Exploration Mastery
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.
- Acknowledge the ambition of the goal.
- Provide 3-5 distinct architectural/functional pathways the user could take.
- 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.
# 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:
❌ 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
❌ 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
### 🔴 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
- Every question = Architectural decision → Not data gathering
- Show trade-offs → User understands consequences
- Prioritize blocking decisions → Cannot proceed without
- Provide defaults → If user doesn't answer, we proceed anyway
- Domain-aware → Ecommerce questions ≠ Auth questions ≠ Real-time questions
- Iterative → More questions as patterns emerge during implementation
AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
- Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
- Hallucinated Libraries/Methods: Using non-existent methods or packages. Always
// VERIFY or check package.json / requirements.txt.
- Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
- Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
- Silent Degradation: Catching and suppressing errors without logging or re-raising.
Slash command: /review or /tribunal-full
Active reviewers: logic-reviewer · security-auditor
❌ Forbidden AI Tropes
- Blind Assumptions: Never make an assumption without documenting it clearly with
// VERIFY: [reason].
- Silent Degradation: Catching and suppressing errors without logging or handling.
- Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
Review these questions before confirming output:
✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?
🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
Pre-Flight Checklist
VBC Protocol (Verification-Before-Completion)
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
🤖 LLM-Specific Traps
AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
- Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
- Hallucinated Libraries/Methods: Using non-existent methods or packages. Always
// VERIFY or check package.json / requirements.txt.
- Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
- Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
- Silent Degradation: Catching and suppressing errors without logging or re-raising.
🏛️ Tribunal Integration (Anti-Hallucination)
Slash command: /review or /tribunal-full
Active reviewers: logic-reviewer · security-auditor
❌ Forbidden AI Tropes
- Blind Assumptions: Never make an assumption without documenting it clearly with
// VERIFY: [reason].
- Silent Degradation: Catching and suppressing errors without logging or handling.
- Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
✅ Pre-Flight Self-Audit
Review these questions before confirming output:
✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?
🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
