brainstorming

# Brainstorming Ideas Into Designs

Turn rough ideas into implementation-ready designs through structured collaborative dialogue using Superpower Loop for continuous iteration.

## CRITICAL: First Action - Start Superpower Loop NOW

**THIS MUST BE YOUR FIRST ACTION. Do NOT explore codebase, do NOT ask questions, do NOT do anything else until you have started the Superpower Loop.**

1. Capture `$ARGUMENTS` as the initial prompt
2. Immediately run:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-superpower-loop.sh" "Brainstorm: $ARGUMENTS. Continue progressing through the superpowers:brainstorming skill phases: Phase 1 (Discovery) → Phase 2 (Option Analysis) → Phase 3 (Design Creation) → Phase 4 (Design Reflection) → Phase 5 (Git Commit) → Phase 6 (Transition)." --completion-promise "BRAINSTORMING_COMPLETE" --max-iterations 50
```
3. Only after the loop is running, proceed to explore the codebase and continue with Phase 1

**The loop enables self-referential iteration throughout the brainstorming process.**

## Superpower Loop Integration

This skill uses Superpower Loop to enable self-referential iteration throughout the brainstorming process.

**CRITICAL**: Throughout the process, you MUST output `<promise>BRAINSTORMING_COMPLETE</promise>` only when:
- Phase 1-4 (Discovery, Option Analysis, Design Creation, Design Reflection) are all complete
- Design folder created with all required documents
- User approval received in Phase 2
- Git commit completed

Do NOT output the promise until ALL conditions are genuinely TRUE.

**ABSOLUTE LAST OUTPUT RULE**: The promise tag MUST be the very last text you output. Output any transition messages or instructions to the user BEFORE the promise tag. Nothing may follow `<promise>BRAINSTORMING_COMPLETE</promise>`.

## Initialization

(The Superpower Loop was already started in the critical first action above - do NOT start it again)

1. **Context Check**: Ensure you have read `CLAUDE.md` and `README.md` to understand project constraints.
2. **Codebase Index**: Verify you have access to the codebase and can run searches.

The loop will continue through all phases until `<promise>BRAINSTORMING_COMPLETE</promise>` is output.

## Core Principles

1. **Converge in Order**: Clarify → Compare → Choose → Design → Reflect → Commit → Transition
2. **Context First**: Explore codebase before asking questions
3. **Incremental Validation**: Validate each phase before proceeding
4. **YAGNI Ruthlessly**: Only include what's explicitly needed
5. **Test-First Mindset**: Always include BDD specifications - load `superpowers:behavior-driven-development` skill

## Phase 1: Discovery

Explore codebase first, then ask focused questions to clarify requirements.

**Actions**:

1. **Explore codebase** - Use Read/Grep/Glob to find relevant files and patterns
2. **Review context** - Check docs/, README.md, CLAUDE.md, recent commits
3. **Identify gaps** - Determine what's unclear from codebase alone
4. **Ask questions** - Use AskUserQuestion with exactly 1 question per call
   - Prefer multiple choice (2-4 options)
   - Ask one at a time, never bundle
   - Base on exploration gaps

**Open-Ended Problem Context**:

If the problem appears open-ended, ambiguous, or requires challenging assumptions:
- Consider applying first-principles thinking to identify the fundamental value proposition
- Question "why" repeatedly to reach core truths
- Be prepared to **explicitly load `superpowers:build-like-iphone-team` skill** in Phase 2 for radical innovation approaches

**Complexity Assessment** (determines sub-agent strategy for Phase 3 & 4):

At the end of discovery, classify the scope:
- **Simple** (single file/component, clear pattern to follow): Skip sub-agents in Phase 3 & 4 — main agent handles directly
- **Medium** (cross-module, some architectural decisions): 2 sub-agents in Phase 3 (Architecture + BDD merged, Context), 2 reflection sub-agents in Phase 4
- **Complex** (new system, large refactor, multiple integration points): Full 3+ sub-agents in Phase 3 and Phase 4

State the assessment explicitly before proceeding.

**Output**: Clear requirements, constraints, success criteria, relevant patterns, and complexity assessment.

See `./references/discovery.md` for detailed patterns and question guidelines.
See `./references/exit-criteria.md` for Phase 1 validation checklist.

## Phase 2: Option Analysis

Research existing patterns, propose viable options, and get user approval.

**Actions**:

1. **Research** - Search codebase for similar implementations
2. **Identify options** - Propose 2-3 grounded in codebase reality, or explain "No Alternatives"
3. **Present** - Write conversationally, lead with recommended option, explain trade-offs
4. **Get approval** - Use AskUserQuestion, ask one question at a time until clear

**Radical Innovation Context**:

If the problem involves:
- Challenging industry conventions or "how things are usually done"
- Creating a new product category rather than improving existing
- Questioning fundamental assumptions
- Open-ended or ambiguous requirements that need disruptive thinking

Then **explicitly load `superpowers:build-like-iphone-team` skill** using the Skill tool to apply iPhone design philosophy (first-principles thinking, breakthrough technology, experience-driven specs, internal competition, Purple Dorm isolation).

**Output**: User-approved approach with rationale and trade-offs understood.

See `./references/options.md` for comparison and presentation patterns.
See `./references/exit-criteria.md` for Phase 2 validation checklist.

## Phase 3: Design Creation

Create design documents. Scale sub-agent usage based on **complexity assessment from Phase 1**.

**Simple**: Main agent handles all research and document creation directly. No sub-agents needed — explore codebase, search for best practices, write BDD scenarios, and create design documents in a single pass.

**Medium** (2 sub-agents):

**Sub-agent 1: Architecture & Best Practices Research**
- Focus: Existing patterns, libraries, WebSearch for best practices, security, performance
- Load `superpowers:behavior-driven-development` skill
- Output: Architecture recommendations, BDD scenarios, best practices summary

**Sub-agent 2: Context & Requirements Synthesis**
- Focus: Synthesize Phase 1 and Phase 2 results
- Output: Context summary, requirements list, success criteria

**Complex** (3+ sub-agents):

**Sub-agent 1: Architecture Research**
- Focus: Existing patterns, architecture, libraries in codebase
- Use WebSearch for latest best practices
- Output: Architecture recommendations with codebase references

**Sub-agent 2: Best Practices Research**
- Focus: Web search for best practices, security, performance patterns
- Load `superpowers:behavior-driven-development` skill
- Output: BDD scenarios, testing strategy, best practices summary

**Sub-agent 3: Context & Requirements Synthesis**
- Focus: Synthesize Phase 1 and Phase 2 results
- Output: Context summary, requirements list, success criteria

**Additional sub-agents**: Launch for distinct, research-intensive aspects as needed.

**Integrate results**: Merge all findings, resolve conflicts, create unified design.

**Design document structure**:

```
docs/plans/YYYY-MM-DD-<topic>-design/
├── _index.md              # Context, Requirements, Rationale, Detailed Design, Design Documents section (MANDATORY)
├── bdd-specs.md           # BDD specifications (MANDATORY)
├── architecture.md        # Architecture details (MANDATORY)
├── best-practices.md      # Best practices and considerations (MANDATORY)
├── decisions/             # ADRs (optional)
└── diagrams/              # Visual artifacts (optional)
```

**CRITICAL: _index.md MUST include Design Documents section with references:**

```markdown
## Design Documents

- [BDD Specifications](./bdd-specs.md) - Behavior scenarios and testing strategy
- [Architecture](./architecture.md) - System architecture and component details
- [Best Practices](./best-practices.md) - Security, performance, and code quality guidelines
```

**Output**: Design folder created with all files saved.

See `./references/design-creation.md` for sub-agent patterns and integration workflow.
See `./references/exit-criteria.md` for Phase 3 validation checklist.

## Phase 4: Design Reflection

Before committing, verify design quality. Scale reflection based on **complexity assessment from Phase 1**.

**Simple**: Main agent performs a single review pass — check requirements coverage, BDD completeness, and document consistency sequentially. No sub-agents needed.

**Medium** (2 reflection sub-agents):

**Sub-agent 1: Requirements & BDD Review**
- Focus: Verify requirements traceability AND BDD scenario completeness (happy path, edge cases, errors)
- Output: Traceability matrix, missing scenarios, coverage gaps

**Sub-agent 2: Consistency & Risk Review**
- Focus: Cross-document terminology, references, component names, and key risks
- Output: Inconsistencies, broken references, unaddressed risks

**Complex** (3+ reflection sub-agents):

**Sub-agent 1: Requirements Traceability Review**
- Focus: Verify every Phase 1 requirement is addressed in design
- Output: Traceability matrix, orphaned requirements list

**Sub-agent 2: BDD Completeness Review**
- Focus: Check BDD scenarios cover happy path, edge cases, and error conditions
- Output: Missing scenarios list, coverage gaps

**Sub-agent 3: Cross-Document Consistency Review**
- Focus: Verify terminology, references, and component names are consistent
- Output: Inconsistencies list, terminology conflicts

**Additional sub-agents (launch as needed)**: Security Review, Risk Assessment.

**Integrate and Update**:
1. Collect all sub-agent findings
2. Prioritize issues by impact
3. Update design documents to fix issues
4. Re-verify updated sections
5. **Confirm with user**: Use AskUserQuestion to present the reflection summary and get approval before committing

**Output**: Updated design documents with issues resolved and user approval received.

See `./references/reflection.md` for sub-agent prompts and integration workflow.

## Phase 5: Git Commit

Commit the design folder using git-agent (with git fallback).

**Actions**:
1. Stage the entire folder: `git add docs/plans/YYYY-MM-DD-<topic>-design/`
2. Run: `git-agent commit --no-stage --intent "add design for <topic>" --co-author "Claude <Model> <Version> <noreply@anthropic.com>"`
3. On auth error, retry with `--free` flag
4. **Fallback**: If git-agent is unavailable or fails, use `git commit -m "docs: add design for <topic> ..."` with conventional format

See `../../skills/references/git-commit.md` for detailed patterns.

## Phase 6: Transition to Implementation

Prompt the user to use `superpowers:writing-plans`, then output the promise as the absolute last line.

Output in this exact order:
1. Transition message: "Design complete. To create a detailed implementation plan, use `/superpowers:writing-plans`."
2. `<promise>BRAINSTORMING_COMPLETE</promise>` — nothing after this

**PROHIBITED**: Do NOT offer to start implementation directly. Do NOT output any text after the promise tag.

## References

- `./references/core-principles.md` - Core principles guiding the workflow
- `./references/discovery.md` - Exploration patterns and question guidelines
- `./references/options.md` - Option comparison and presentation patterns
- `./references/design-creation.md` - Sub-agent patterns, integration workflow, design structure
- `./references/reflection.md` - Design reflection patterns and gap identification strategies
- `./references/exit-criteria.md` - Validation checklists, success indicators, common pitfalls
- `../../skills/references/git-commit.md` - Git commit patterns and requirements (shared cross-skill resource)
- `../../skills/references/loop-patterns.md` - Completion promise design, prompt patterns, and safety nets