brainstorming

Visão geral

O que a skill brainstorming faz

A skill brainstorming impõe uma regra clara: primeiro vêm o design e a especificação, depois a implementação. Quando habilitada, a brainstorming orienta você a explorar a intenção do usuário, os requisitos e o design em alto nível antes de escrever código, criar scaffolds de projetos ou acionar qualquer skill de implementação.

Ela é construída em torno de um diálogo colaborativo. Você parte de uma ideia bruta, refina contexto e restrições por meio de perguntas direcionadas e, então, converge para um design e uma especificação explícitos que o usuário possa revisar e aprovar. Só depois de passar por esse gate rígido de aprovação é apropriado partir para o trabalho de build ou refatoração.

Para quem é a brainstorming

Use a skill brainstorming se você:

• Trabalha com Claude ou agentes similares em features de produto, componentes, fluxos de UI ou mudanças de arquitetura
• Quer evitar o antipadrão de “isso é simples demais para precisar de design”
• Precisa de conversas de design repetíveis e auditáveis antes de mudanças de código
• Frequente­mente constrói ou ajusta frontend, UI/UX ou sistemas com fluxos complexos

Ela é adequada para devs solo, product engineers, designers e times que querem um fluxo leve, porém consistente, com design em primeiro lugar.

Problemas que esta skill resolve

A skill brainstorming foi desenhada para evitar:

• Cair direto no código sem clarificar objetivos
• Suposições ocultas que só aparecem tarde na implementação
• Mudanças de UI/UX feitas sem jornadas do usuário claras ou direção visual
• Specs vagas demais para planejamento ou delegação confiáveis

Ao forçar um checkpoint de design, a brainstorming reduz retrabalho, implementação desalinhada e dívida de design.

Quando a brainstorming é uma boa (ou má) opção

É uma ótima opção quando:

• Você está planejando novas features, modificando comportamentos ou desenhando fluxos de UI/UX
• Você quer um template estruturado para ideação, coleta de contexto e aprovação de design
• Você se beneficia de mockups ou diagramas visuais ao analisar alternativas

É menos indicada quando:

• Você está fazendo edições puramente mecânicas (correção de typo, renomear uma variável, atualizar uma constante sem mudança de comportamento)
• Você já tem uma spec detalhada e aprovada e só vai executá‑la (nesse caso, faz mais sentido usar skills focadas em implementação)

Mesmo tarefas aparentemente triviais, como uma pequena mudança de config ou uma utility de função única, podem se beneficiar de uma passada rápida de design — que pode ser breve, mas ainda seguindo o processo de brainstorming.

Como usar

Instalação e configuração

1. Instale a skill brainstorming

Use o skills CLI para adicionar a skill brainstorming a partir do repositório obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill brainstorming

Isso traz a definição da skill mais os prompts de suporte e scripts auxiliares opcionais para o diretório skills/brainstorming.

2. Explore os arquivos principais

Após a instalação, revise estes arquivos para entender o fluxo de trabalho e os helpers disponíveis:

• SKILL.md – Descrição central do processo de brainstorming, incluindo o gate rígido de design-before-code e o checklist de etapas obrigatórias.
• spec-document-reviewer-prompt.md – Prompt template para um subagente revisor de spec que verifica completude, consistência e clareza da sua spec.
• visual-companion.md – Guia para usar um visual companion baseado em browser para exibir mockups, diagramas e opções visuais.
• scripts/frame-template.html – Template de frame HTML usado pelo visual companion para layouts consistentes focados em UI.
• scripts/helper.js – Helper client-side para lidar com eventos de seleção e live reload no visual companion.
• scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh – Scripts para rodar e gerenciar o servidor do visual companion.

Você não precisa modificar esses arquivos para começar a usar o fluxo de brainstorming, mas saber o que está disponível ajuda a integrá‑lo ao seu próprio setup.

Workflow principal de brainstorming

1. Comece pelo contexto do projeto

Inicie qualquer sessão de brainstorming se situando no projeto atual. O checklist em SKILL.md enfatiza:

• Inspecionar arquivos e docs relevantes
• Passar o olho em commits recentes para contexto
• Identificar quais partes do sistema estão envolvidas

Ao usar o Claude ou outro agente, peça explicitamente para explorar o contexto do projeto primeiro, em vez de solicitar mudanças de código de imediato.

2. Ofereça o visual companion para questões visuais

Se a tarefa envolver UI/UX ou outros tópicos inerentemente visuais, ofereça o uso do visual companion como uma etapa separada. A regra de visual-companion.md é:

Decida por pergunta, não por sessão. Pergunte: o usuário entenderia isso melhor vendo do que lendo?

Use o visual companion (no navegador) para:

• Mockups de UI e opções de layout
• Diagramas de arquitetura e de fluxos
• Comparações lado a lado de direções de design
• Conversas sobre espaçamento, hierarquia e polimento visual

Fique no terminal (somente texto) para:

• Escopo, requisitos e definições de termos
• Tradeoffs conceituais e escolhas de modelagem de API/dados
• Perguntas de esclarecimento em que as respostas são palavras, não visuais

3. Faça perguntas de esclarecimento uma de cada vez

A skill brainstorming pressupõe uma conversa disciplinada, não um único mega-prompt. Use uma sequência de perguntas focadas, por exemplo:

• "Who are the primary users of this feature?"
• "What constraints do we have on performance or deployment?"
• "Which platforms and screen sizes matter most?"

Faça uma pergunta por vez, espere as respostas e refine seu entendimento de forma incremental.

4. Produza um design e uma spec concretos

Quando tiver contexto suficiente, sintetize tudo em um design que o usuário possa de fato aprovar. Dependendo da tarefa, isso pode incluir:

• Objetivos em alto nível e critérios de sucesso
• User stories ou fluxos de exemplo
• Descrições de layout de UI e direções visuais (opcionalmente apoiadas pelo visual companion)
• Estruturas de dados, interfaces ou pontos de integração
• Requisitos não funcionais que afetem a implementação

Escreva isso como um documento de spec estruturado no local de sua preferência (por exemplo, em docs/superpowers/specs/ se você seguir a convenção do repositório).

5. Faça valer o hard design gate

Uma regra chave de SKILL.md é o hard gate:

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

Isso vale mesmo quando o trabalho parece simples. O design pode ter só algumas frases para uma mudança trivial, mas ele precisa existir e ser explicitamente confirmado antes de seguir em frente.

Usando o template de revisão de spec

1. Rascunhe sua spec

Depois do brainstorming, faça o rascunho da sua spec usando a estrutura que melhor funcione no seu projeto. Salve em um caminho de arquivo que você possa referenciar, como:

docs/superpowers/specs/my-feature-spec.md

2. Dispare um subagente revisor de spec

Quando a spec estiver pronta para validação, use spec-document-reviewer-prompt.md como template para subir um subagente revisor de spec. Substitua [SPEC_FILE_PATH] no prompt pelo caminho do arquivo da sua spec.

Esse revisor vai:

• Verificar se há seções faltando, TODOs ou placeholders “TBD”
• Procurar contradições e requisitos inconsistentes
• Apontar requisitos ambíguos que possam causar má implementação
• Garantir que o escopo esteja enxuto o suficiente para um plano único e coerente

A saída do revisor inclui um status Approved | Issues Found e uma lista de issues, cada uma ligada a por que aquilo importa para o planejamento da implementação.

3. Itere até obter aprovação

Se o revisor encontrar problemas, atualize a spec e rode a revisão novamente. Depois que sua spec for aprovada, você terá uma base sólida para skills de implementação e ferramentas de planejamento.

Usando o visual brainstorming companion

1. Inicie o servidor do visual companion

No diretório scripts, você pode iniciar o servidor de brainstorming com:

./start-server.sh --project-dir /path/to/your/project

Opções úteis incluem:

• --project-dir <path> – Armazena arquivos de sessão em <path>/.superpowers/brainstorm/ em vez de /tmp, para persistência.
• --host <bind-host> – Faz bind em uma interface específica (por exemplo, 0.0.0.0 em containers ou ambientes remotos).
• --url-host <display-host> – Controla o hostname exibido no JSON com a URL retornada.
• --foreground ou --background – Define se o servidor roda no terminal atual ou como processo em background.

Na inicialização, o script imprime um JSON com a URL da sessão. Abra essa URL no navegador para acessar o frame de brainstorming visual.

2. Renderize opções visuais

O servidor observa um diretório em busca de arquivos HTML e sempre serve o arquivo mais recente. O padrão típico é:

1. Claude (ou seu agente) grava um arquivo HTML no screen_dir configurado usando frame-template.html como base.
2. O navegador faz reload automático via helper.js quando um novo arquivo é criado.
3. Usuários podem clicar em opções ou cards na UI, e esses eventos são enviados por WebSocket para o agente consumir.

Isso facilita mostrar:

• Múltiplas opções de layout como cards clicáveis
• Diagramas de fluxo e máquinas de estados
• Comparações visuais de cor, espaçamento ou variantes de componentes

3. Pare o servidor ao terminar

Quando a sessão terminar, pare o servidor de brainstorming de forma limpa usando:

./stop-server.sh <session_dir>

Para sessões em /tmp, isso também limpa os arquivos gerados. Diretórios persistentes em .superpowers/ são preservados para que você possa revisitar mockups e diagramas depois.

Integrando a brainstorming ao seu próprio fluxo

• Como etapa padrão antes de commits: Exigir uma passada de brainstorming e uma spec aprovada antes de fazer merge de feature branches.
• Com outras skills: Rode a brainstorming primeiro, capture a spec e só então entregue para skills de implementação, refatoração ou testes.
• Para trabalho de UI/UX: Combine o brainstorming conversacional com o visual companion para validar ideias de layout e interação antes de escrever qualquer código de CSS ou de componente.

Ajuste paths de pastas, nomes e formato de spec para bater com seus repositórios atuais, mantendo o padrão central: contexto → perguntas → design/spec → revisão → implementação.

FAQ

A skill brainstorming é só para projetos grandes e complexos?

Não. A skill brainstorming foi criada justamente para evitar o antipadrão de “isso é simples demais para precisar de design”. Mesmo uma pequena mudança de config ou um utilitário pontual pode esconder suposições. Para tarefas muito pequenas, o design pode ser apenas uma descrição concisa, mas ainda assim você deve articulá‑lo e confirmá‑lo antes da implementação.

Posso pular o brainstorming se eu já tiver uma spec?

Se você já tiver uma spec completa, atualizada e aprovada, talvez não precise de uma sessão de brainstorming completa. Ainda assim, você pode usar o template de revisão de spec em spec-document-reviewer-prompt.md para validar essa spec antes da implementação. Se a revisão apontar gaps ou ambiguidades, rode uma passada mais curta de brainstorming para fechá‑los.

Como a brainstorming funciona junto com skills de implementação?

A skill brainstorming foi feita para rodar antes de qualquer skill de implementação. Ela produz:

• Um design claro, aprovado pelo usuário
• Um documento de spec que pode ser revisado e iterado

Só depois que esse gate de aprovação for cumprido é que você deve acionar skills de código ou refatoração. Essa separação ajuda a manter a intenção de design explícita e reduz idas e vindas durante a implementação.

Preciso usar o visual companion para aproveitar a brainstorming?

Não. O visual companion é opcional.

• Se seu trabalho é majoritariamente de backend, APIs ou infraestrutura, você pode usar a brainstorming como um fluxo puramente baseado em texto.
• Se você trabalha com UI/UX, product design ou frontend, usar o visual companion descrito em visual-companion.md e no diretório scripts/ pode facilitar bastante a comparação de opções e a coleta de feedback.

Escolha com base em se visuais realmente vão deixar a conversa mais clara.

O que acontece se eu ignorar o hard gate e começar a codar mesmo assim?

Ignorar o hard design gate elimina o principal benefício da skill brainstorming: detectar desalinhamentos cedo. Você pode acabar com:

• Features que não correspondem às expectativas dos usuários
• Implementações de UI que precisam ser refeitas depois do feedback
• Specs que ficam atrás do código e viram dívida de documentação

Trate o gate como uma regra de processo: não escreva nem peça código até que o design esteja escrito, revisado e explicitamente aprovado.

Posso customizar os critérios de revisão da spec?

Sim. spec-document-reviewer-prompt.md define categorias como completude, consistência, clareza, escopo e considerações de YAGNI. Você pode adaptar esse template ao seu domínio (por exemplo, adicionando checagens de segurança, performance ou compliance) mantendo o mesmo fluxo de revisão.

A brainstorming é ligada a algum framework ou stack específico?

Não. A skill brainstorming é agnóstica de stack. Ela foca em coleta de contexto, esclarecimento de requisitos, explicitação de design e exploração visual — não em código específico de framework. Você pode usá‑la em apps frontend, serviços backend, integrações ou sistemas mistos.

Como desinstalo ou desabilito a skill brainstorming?

A skill é apenas parte do conjunto de skills obra/superpowers. Para parar de usá‑la, você pode:

• Remover ou comentar sua configuração no seu agente ou loader de skills
• Parar de chamá‑la nos seus workflows e pipelines

A skill brainstorming em si não faz alterações globais no sistema; então, removê‑la é apenas uma questão de configuração e uso.