---
name: brainstorming
description: Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements. Includes progress reporting and error handling.
allowed-tools: Read, Glob, Grep
---

# Brainstorming & Communication Protocol

> **MANDATORY:** Use for complex/vague requests, new features, updates.

---

## 🛑 SOCRATIC GATE (ENFORCEMENT)

### When to Trigger

| Pattern                                     | Action                             |
| ------------------------------------------- | ---------------------------------- |
| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions                 |
| Complex feature or architecture             | 🛑 Clarify before implementing     |
| Update/change request                       | 🛑 Confirm scope                   |
| Vague requirements                          | 🛑 Ask purpose, users, constraints |

### 🚫 MANDATORY: 3 Questions Before Implementation

1. **STOP** - Do NOT start coding
2. **ASK** - Minimum 3 questions:
   - 🎯 Purpose: What problem are you solving?
   - 👥 Users: Who will use this?
   - 📦 Scope: Must-have vs nice-to-have?
3. **WAIT** - Get response before proceeding

---

## 🧠 Dynamic Question Generation

**⛔ NEVER use static templates.** Read `dynamic-questioning.md` for principles.

### Core Principles

| Principle                          | Meaning                                                    |
| ---------------------------------- | ---------------------------------------------------------- |
| **Questions Reveal Consequences**  | Each question connects to an architectural decision        |
| **Context Before Content**         | Understand greenfield/feature/refactor/debug context first |
| **Minimum Viable Questions**       | Each question must eliminate implementation paths          |
| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs                            |

### Question Generation Process

```
1. Parse request → Extract domain, features, scale indicators
2. Identify decision points → Blocking vs. deferable
3. Generate questions → Priority: P0 (blocking) > P1 (high-leverage) > P2 (nice-to-have)
4. Format with trade-offs → What, Why, Options, Default
```

### Question Format (MANDATORY)

```markdown
### [PRIORITY] **[DECISION POINT]**

**Question:** [Clear question]

**Why This Matters:**

- [Architectural consequence]
- [Affects: cost/complexity/timeline/scale]

**Options:**
| Option | Pros | Cons | Best For |
|--------|------|------|----------|
| A | [+] | [-] | [Use case] |

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

**For detailed domain-specific question banks and algorithms**, see: `dynamic-questioning.md`

---

## Progress Reporting (PRINCIPLE-BASED)

**PRINCIPLE:** Transparency builds trust. Status must be visible and actionable.

### Status Board Format

| Agent        | Status     | Current Task       | Progress     |
| ------------ | ---------- | ------------------ | ------------ |
| [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |

### Status Icons

| Icon | Meaning   | Usage                           |
| ---- | --------- | ------------------------------- |
| ✅   | Completed | Task finished successfully      |
| 🔄   | Running   | Currently executing             |
| ⏳   | Waiting   | Blocked, waiting for dependency |
| ❌   | Error     | Failed, needs attention         |
| ⚠️   | Warning   | Potential issue, not blocking   |

---

## Error Handling (PRINCIPLE-BASED)

**PRINCIPLE:** Errors are opportunities for clear communication.

### Error Response Pattern

```
1. Acknowledge the error
2. Explain what happened (user-friendly)
3. Offer specific solutions with trade-offs
4. Ask user to choose or provide alternative
```

### Error Categories

| Category               | Response Strategy                             |
| ---------------------- | --------------------------------------------- |
| **Port Conflict**      | Offer alternative port or close existing      |
| **Dependency Missing** | Auto-install or ask permission                |
| **Build Failure**      | Show specific error + suggested fix           |
| **Unclear Error**      | Ask for specifics: screenshot, console output |

---

## Completion Message (PRINCIPLE-BASED)

**PRINCIPLE:** Celebrate success, guide next steps.

### Completion Structure

```
1. Success confirmation (celebrate briefly)
2. Summary of what was done (concrete)
3. How to verify/test (actionable)
4. Next steps suggestion (proactive)
```

---

## Communication Principles

| Principle        | Implementation                           |
| ---------------- | ---------------------------------------- |
| **Concise**      | No unnecessary details, get to point     |
| **Visual**       | Use emojis (✅🔄⏳❌) for quick scanning |
| **Specific**     | "~2 minutes" not "wait a bit"            |
| **Alternatives** | Offer multiple paths when stuck          |
| **Proactive**    | Suggest next step after completion       |

---

## Anti-Patterns (AVOID)

| Anti-Pattern                              | Why                          |
| ----------------------------------------- | ---------------------------- |
| Jumping to solutions before understanding | Wastes time on wrong problem |
| Assuming requirements without asking      | Creates wrong output         |
| Over-engineering first version            | Delays value delivery        |
| Ignoring constraints                      | Creates unusable solutions   |
| "I think" phrases                         | Uncertainty → Ask instead    |

---

## ⛔ HARD-GATE: No Code Before Design Approval

> Adapted from obra/superpowers.

Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.

**"Simple" projects are where unexamined assumptions cause the most wasted work.** The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

---

## Propose Approaches

Before settling on a design:

1. **Propose 2-3 different approaches** with trade-offs
2. **Lead with your recommendation** and explain why
3. **Present options conversationally** — not exhaustive specs
4. **Wait for user preference** before detailing the chosen approach

---

## Design Document

After the user approves the design:

1. Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md` (or project root as `{task-slug}.md`)
2. Commit the design document
3. **Transition to implementation** — invoke `plan-writing` skill to create detailed implementation plan

> 🔴 **The terminal state of brainstorming is always `plan-writing`.** Do NOT invoke any implementation skill directly from brainstorming.

---

## Integration

| Skill                     | Relationship                              |
| ------------------------- | ----------------------------------------- |
| `plan-writing`            | Next step after design approval           |
| `executing-plans`         | Executes the plan created by plan-writing |
| `test-driven-development` | Referenced in plan tasks                  |

## AGI Framework Integration

### Qdrant Memory Integration

Before executing complex tasks with this skill:
```bash
python3 execution/memory_manager.py auto --query "<task summary>"
```

**Decision Tree:**
- **Cache hit?** Use cached response directly — no need to re-process.
- **Memory match?** Inject `context_chunks` into your reasoning.
- **No match?** Proceed normally, then store results:

```bash
python3 execution/memory_manager.py store \
  --content "Description of what was decided/solved" \
  --type decision \
  --tags brainstorming <relevant-tags>
```

> **Note:** Storing automatically updates both Vector (Qdrant) and Keyword (BM25) indices.

### Agent Team Collaboration

- **Strategy**: This skill communicates via the shared memory system.
- **Orchestration**: Invoked by `orchestrator` via intelligent routing.
- **Context Sharing**: Always read previous agent outputs from memory before starting.

### Local LLM Support

When available, use local Ollama models for embedding and lightweight inference:
- Embeddings: `nomic-embed-text` via Qdrant memory system
- Lightweight analysis: Local models reduce API costs for repetitive patterns
