bee:brainstorming

Category: Content & Multimedia | Uploader: luanrodrigues | Downloads: 0 | Version: v1.0（Latest）
Socratic design refinement - transforms rough ideas into validated designs through structured questioning, alternative exploration, and incremental validation.
Changelog: Source: GitHub https://github.com/luanrodrigues/ia-frmwrk
Directory Structure

Current level: default/skills/brainstorming/
📄 SKILL.md 13.2 KB
SKILL.md

---
name: bee:brainstorming
description: |
  Socratic design refinement - transforms rough ideas into validated designs through
  structured questioning, alternative exploration, and incremental validation.

trigger: |
  - New feature or product idea (requirements unclear)
  - User says "plan", "design", or "architect" something
  - Multiple approaches seem possible
  - Design hasn't been validated by user

skip_when: |
  - Design already complete and validated → use bee:writing-plans
  - Have detailed plan ready to execute → use bee:executing-plans
  - Just need task breakdown from existing design → use bee:writing-plans

sequence:
  before: [bee:writing-plans, bee:using-git-worktrees]

related:
  similar: [bee:writing-plans]
---

# Brainstorming Ideas Into Designs

## Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.

**Announce at start:** "I'm using the bee:brainstorming skill to refine your idea into a design."

## Quick Reference

| Phase | Key Activities | Tool Usage | Output |
|-------|---------------|------------|--------|
| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |
| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |
| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
| **5. Worktree Setup** | Set up isolated workspace | bee:using-git-worktrees skill | Ready development environment |
| **6. Planning Handoff** | Create implementation plan | bee:writing-plans skill | Detailed task breakdown |

## The Process

Copy this checklist to track progress:

```
Brainstorming Progress:
- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- [ ] Phase 5: Worktree Setup (if implementing)
- [ ] Phase 6: Planning Handoff (if implementing)
```

### Prep: Autonomous Recon

**MANDATORY evidence (paste ALL):** `ls -la`, `git log --oneline -10`, `head -50 README.md`, `find . -name "*test*" | wc -l`, check package.json/requirements.txt/go.mod.

**Only after ALL evidence pasted:** Form your model and share findings. **Skip any = not following skill.**

### Question Budget

**Maximum 3 questions per phase.** More = insufficient research.

Question count:
- Phase 1: ___/3
- Phase 2: ___/3
- Phase 3: ___/3

Hit limit? Do research instead of asking.

### Phase 1: Understanding
- Share your synthesized understanding first, then invite corrections or additions.
- Ask one focused question at a time, only for gaps you cannot close yourself.
- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.
- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)

**Example summary + targeted question:**
```
Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?
```

### Phase Lock Rules

**CRITICAL:** Once you enter a phase, you CANNOT skip ahead.

- Asked a question? → WAIT for answer before solutions
- Proposed approaches? → WAIT for selection before design
- Started design? → COMPLETE before documentation

**Violations:**
- "While you consider that, here's my design..." → WRONG
- "I'll proceed with option 1 unless..." → WRONG
- "Moving forward with the assumption..." → WRONG

**WAIT means WAIT. No assumptions.**

### Phase 2: Exploration
- Propose 2-3 different approaches
- For each: Core architecture, trade-offs, complexity assessment, and your recommendation
- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call
- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking

**Example using AskUserQuestion:**
```
Question: "Which architectural approach should we use?"
Options:
  - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
  - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
  - "Hybrid with background jobs" (balanced, moderate complexity, best of both)

I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.
```

### Phase 3: Design Presentation
- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
- Cover: Architecture, components, data flow, error handling, testing
- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
- Use open-ended questions to allow freeform feedback
- Assume ownership and proceed unless your partner redirects you

**Design Acceptance Gate:**

Design is NOT approved until human EXPLICITLY says one of:
- "Approved" / "Looks good" / "Proceed"
- "Let's implement that" / "Ship it"
- "Yes" (in response to "Shall I proceed?")

**These do NOT mean approval:**
- Silence / No response
- "Interesting" / "I see" / "Hmm"
- Questions about the design
- "What about X?" (that's requesting changes)

**No explicit approval = keep refining**

### Phase 4: Design Documentation
After validating the design, write it to a permanent document:
- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
- Commit the design document to git before proceeding

### Phase 5: Worktree Setup (for implementation)
When design is approved and implementation will follow:
- Announce: "I'm using the bee:using-git-worktrees skill to set up an isolated workspace."
- **REQUIRED SUB-SKILL:** Use bee:using-git-worktrees
- Follow that skill's process for directory selection, safety verification, and setup
- Return here when worktree ready

### Phase 6: Planning Handoff
Ask: "Ready to create the implementation plan?"

When your human partner confirms (any affirmative response):
- Announce: "I'm using the bee:writing-plans skill to create the implementation plan."
- **REQUIRED SUB-SKILL:** Use bee:writing-plans
- Create detailed plan in the worktree

## Question Patterns

### When to Use AskUserQuestion Tool

**Use AskUserQuestion when:**
- You need your partner to make a judgement call among real alternatives
- You have a recommendation and can explain why it’s your preference
- Prioritization is ambiguous and cannot be inferred from existing materials

**Best practices:**
- State your preferred option and rationale inside the question so your partner can agree or redirect
- If you know the answer from repo/docs, state it as fact and proceed—no question needed
- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner

### When to Use Open-Ended Questions

**Use open-ended questions for:**
- Phase 3: Design validation ("Does this look right so far?")
- When you need detailed feedback or explanation
- When partner should describe their own requirements
- When structured options would limit creative input

Frame them to confirm or expand your current understanding rather than reopening settled topics.

**Example decision flow:**
- "What authentication method?" → Use AskUserQuestion (2-4 options)
- "Does this design handle your use case?" → Open-ended (validation)

## When to Revisit Earlier Phases

| Trigger | Action |
|---------|--------|
| New constraint revealed | → Return to Phase 1 |
| Partner questions approach | → Return to Phase 2 |
| Requirements unclear | → Return to Phase 1 |
| Something doesn't make sense | → Go back and clarify |

**Avoid forcing forward linearly** when going backward would give better results.

## Required Patterns

This skill uses these universal patterns:
- **State Tracking:** See `skills/shared-patterns/state-tracking.md`
- **Failure Recovery:** See `skills/shared-patterns/failure-recovery.md`
- **Exit Criteria:** See `skills/shared-patterns/exit-criteria.md`
- **TodoWrite:** See `skills/shared-patterns/todowrite-integration.md`

Apply ALL patterns when using this skill.

## Key Principles

| Principle | Application |
|-----------|-------------|
| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself |
| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
| **YAGNI ruthlessly** | Remove unnecessary features from all designs |
| **Explore alternatives** | Always propose 2-3 approaches before settling |
| **Incremental validation** | Present design in sections, validate each |
| **Flexible progression** | Go backward when needed - flexibility > rigidity |
| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |
| **Announce usage** | State skill usage at start of session |

## Blocker Criteria

STOP and report if:

| Decision Type | Blocker Condition | Required Action |
|---|---|---|
| Phase progression | User has not explicitly approved design | STOP and wait for explicit approval |
| Question budget | Exceeded 3 questions per phase | STOP asking questions, do research instead |
| Phase lock | Attempting to skip ahead before phase completion | STOP and complete current phase first |
| Design validation | Received ambiguous response (not explicit approval) | STOP and clarify approval status |
| Sub-skill handoff | Required sub-skill unavailable or blocked | STOP and report blocker |

### Cannot Be Overridden

The following requirements CANNOT be waived:
- MUST follow phase lock rules - CANNOT skip ahead while waiting for answers
- MUST have explicit design approval - silence or "interesting" does not mean approval
- CANNOT exceed question budget of 3 per phase - research instead
- MUST paste autonomous recon evidence before forming model
- CANNOT skip sub-skill usage (bee:writing-plans, bee:using-git-worktrees) when applicable

## Severity Calibration

| Severity | Condition | Required Action |
|---|---|---|
| CRITICAL | Proceeding without explicit design approval | MUST stop immediately and obtain approval |
| CRITICAL | Skipping phases or phase lock violation | MUST return to correct phase |
| HIGH | Exceeding question budget without research | MUST do research before asking more questions |
| HIGH | Missing autonomous recon evidence | MUST gather and paste evidence |
| MEDIUM | Not using AskUserQuestion for structured choices | Should use proper tool for decisions |
| LOW | Minor documentation gaps in design doc | Fix in next iteration |

## Pressure Resistance

| User Says | Your Response |
|---|---|
| "Just skip the exploration phase, I know what I want" | "MUST complete Phase 2 exploration to ensure we consider alternatives. This prevents costly rework later." |
| "I said it looks good, just proceed" | "MUST have explicit approval like 'approved' or 'proceed'. 'Looks good' is ambiguous - shall I proceed with implementation?" |
| "Stop asking questions and just build it" | "MUST gather understanding before building. I'll research the codebase to minimize questions while ensuring we build the right thing." |
| "We don't have time for all these phases" | "Phases exist to prevent expensive mistakes. Skipping them creates technical debt. MUST follow the process." |

## Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "User seems to approve, no need for explicit confirmation" | Implicit approval leads to misaligned implementations and wasted effort | **MUST obtain explicit approval words** |
| "I already know the codebase, skip autonomous recon" | Assumptions cause errors; evidence ensures accuracy | **MUST paste recon evidence before proceeding** |
| "This is a simple feature, phases are overkill" | Complexity is often hidden; phases reveal it | **MUST complete all applicable phases** |
| "User is impatient, I'll ask questions later" | Phase lock exists to prevent building wrong things | **MUST wait for answers before solutions** |
| "I can infer the decision from context" | Inference is not explicit choice; user must decide | **MUST use AskUserQuestion for real decisions** |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
bee:brainstorming

Directory Structure

SKILL.md

Report

Notice
