brainstorming

Vue d’ensemble

Ce que fait la compétence brainstorming

La compétence brainstorming impose une règle claire : d’abord la conception et la spécification, ensuite seulement la mise en œuvre. Une fois activée, brainstorming vous guide pour explorer l’intention utilisateur, les exigences et la conception de haut niveau avant d’écrire du code, de créer l’ossature d’un projet ou d’appeler une compétence d’implémentation.

Elle est conçue autour d’un dialogue collaboratif. Vous partez d’une idée encore floue, affinez le contexte et les contraintes grâce à des questions ciblées, puis convergeez vers une conception et une spec explicites que l’utilisateur peut relire et approuver. Ce n’est qu’après ce point de validation explicite qu’il est pertinent de passer au développement ou au refactoring.

Pour qui la compétence brainstorming est-elle faite ?

Utilisez la compétence brainstorming si vous :

• Travaillez avec Claude ou des agents similaires sur des fonctionnalités produit, des composants, des parcours UI ou des changements d’architecture
• Souhaitez éviter l’anti‑pattern « c’est trop simple pour nécessiter une conception »
• Avez besoin de conversations de conception répétables et auditables avant les changements de code
• Travaillez souvent sur des frontends, de l’UI/UX ou des systèmes très orientés workflows

Elle convient aussi bien aux développeurs solo, aux ingénieurs produit, aux designers qu’aux équipes qui veulent un workflow “design‑first” léger mais cohérent.

Problèmes que cette compétence résout

La compétence brainstorming est conçue pour éviter :

• Le passage direct au code sans clarification des objectifs
• Les hypothèses cachées qui n’apparaissent qu’en fin d’implémentation
• Les changements UI/UX réalisés sans parcours utilisateur clair ni direction visuelle définie
• Les specs trop vagues pour permettre une planification ou une délégation fiables

En imposant un point de passage par la conception, brainstorming réduit le rework, les implémentations mal alignées et la dette de design.

Quand la compétence brainstorming est-elle adaptée (ou non) ?

Particulièrement adaptée lorsque :

• Vous planifiez de nouvelles fonctionnalités, modifiez un comportement ou concevez des parcours UI/UX
• Vous voulez un canevas structuré pour l’idéation, la collecte de contexte et la validation de la conception
• Vous bénéficiez de maquettes ou de diagrammes visuels pour comparer les options

Moins adaptée lorsque :

• Vous faites des modifications purement mécaniques (correction de typo, renommage d’une variable, mise à jour d’une constante sans changement de comportement)
• Vous avez déjà une spec détaillée et validée et ne faites que l’exécuter (dans ce cas, utilisez plutôt des compétences orientées implémentation)

Même des tâches en apparence triviales, comme un petit changement de config ou une fonction utilitaire isolée, peuvent tirer profit d’un court passage par la conception. Vous pouvez garder ce passage très bref tout en restant dans le processus brainstorming.

Utilisation

Installation et configuration

1. Installer la compétence brainstorming

Utilisez le CLI skills pour ajouter la compétence brainstorming depuis le dépôt obra/superpowers :

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

Cette commande récupère la définition de la compétence ainsi que les prompts associés et les scripts d’assistance optionnels sous le répertoire skills/brainstorming.

2. Explorer les fichiers clés

Après l’installation, consultez ces fichiers pour comprendre le workflow et les helpers disponibles :

• SKILL.md – Description centrale du processus brainstorming, incluant la règle stricte design‑avant‑code et la checklist des étapes requises.
• spec-document-reviewer-prompt.md – Prompt modèle pour un sous‑agent de revue de spec qui vérifie l’exhaustivité, la cohérence et la clarté de votre spec.
• visual-companion.md – Guide d’utilisation d’un compagnon visuel dans le navigateur pour afficher maquettes, diagrammes et variantes visuelles.
• scripts/frame-template.html – Gabarit HTML de frame utilisé par le compagnon visuel pour des mises en page orientées UI cohérentes.
• scripts/helper.js – Helper côté client pour gérer les événements de sélection et le live reload dans le compagnon visuel.
• scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh – Scripts pour exécuter et gérer le serveur du compagnon visuel.

Vous n’avez pas besoin de modifier ces fichiers pour commencer à utiliser le workflow brainstorming, mais savoir ce qui existe vous aide à l’intégrer dans votre propre environnement.

Workflow central de brainstorming

1. Commencer par le contexte du projet

Démarrez chaque session brainstorming en vous replaçant dans le contexte du projet en cours. La checklist de SKILL.md met l’accent sur :

• L’inspection des fichiers et documents pertinents
• Le survol des commits récents pour le contexte
• L’identification des parties du système concernées

Avec Claude ou un autre agent, demandez‑lui d’explorer d’abord le contexte du projet plutôt que de solliciter immédiatement des changements de code.

2. Proposer le compagnon visuel pour les questions visuelles

Si la tâche implique de l’UI/UX ou d’autres sujets intrinsèquement visuels, proposez d’utiliser le compagnon visuel dans une étape distincte. La règle décrite dans visual-companion.md est :

Décidez question par question, pas session par session. Demandez‑vous : l’utilisateur comprendrait‑il mieux en voyant qu’en lisant ?

Utilisez le compagnon dans le navigateur pour :

• Des maquettes UI et options de layout
• Des diagrammes d’architecture et de flux
• Des comparaisons côte à côte de directions de design
• Des discussions sur les espacements, la hiérarchie et la finition visuelle

Restez dans le terminal (texte seul) pour :

• Le périmètre, les exigences et les définitions de termes
• Les compromis conceptuels et les choix d’API/modélisation des données
• Les questions de clarification dont les réponses sont verbales, pas visuelles

3. Poser les questions de clarification une par une

La compétence brainstorming suppose une conversation disciplinée, pas un mega‑prompt unique. Utilisez une suite de questions ciblées, par exemple :

• « Qui sont les utilisateurs principaux de cette fonctionnalité ? »
• « Quelles contraintes avons‑nous sur les performances ou le déploiement ? »
• « Quelles plates‑formes et tailles d’écran comptent le plus ? »

Posez une question à la fois, attendez les réponses et affinez progressivement votre compréhension.

4. Produire une conception et une spec concrètes

Une fois le contexte suffisamment clarifié, synthétisez‑le en une conception que l’utilisateur peut réellement approuver. Selon la tâche, cela peut inclure :

• Des objectifs de haut niveau et des critères de succès
• Des user stories ou des parcours d’exemple
• Des descriptions de layout UI et des directions visuelles (éventuellement appuyées par le compagnon visuel)
• Des structures de données, interfaces ou points d’intégration
• Des exigences non fonctionnelles qui influencent l’implémentation

Rédigez cela sous forme de document de spec structuré à l’emplacement qui vous convient (par exemple sous docs/superpowers/specs/ si vous suivez la convention du dépôt).

5. Faire respecter le “hard gate” de conception

Une règle clé de SKILL.md est le “hard gate” :

Ne faites appel à aucune compétence d’implémentation, n’écrivez aucun code, ne générez aucun squelette de projet et n’entreprenez aucune action d’implémentation tant que vous n’avez pas présenté une conception et que l’utilisateur ne l’a pas approuvée.

Cela s’applique même quand le travail semble simple. Pour un changement trivial, la conception peut se résumer à quelques phrases, mais elle doit exister et être explicitement validée avant d’avancer.

Utiliser le modèle de revue de document de spec

1. Rédiger votre spec

Après la phase de brainstorming, rédigez votre spec avec la structure qui convient à votre projet. Enregistrez‑la dans un fichier que vous pourrez référencer, par exemple :

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

2. Lancer un sous‑agent de revue de spec

Quand la spec est prête à être validée, utilisez spec-document-reviewer-prompt.md comme modèle pour lancer un sous‑agent de revue de spec. Remplacez [SPEC_FILE_PATH] dans le prompt par le chemin de votre fichier de spec.

Ce reviewer va :

• Vérifier les sections manquantes, les TODO ou les placeholders « TBD »
• Rechercher les contradictions et exigences incohérentes
• Signaler les exigences ambiguës susceptibles de provoquer une mauvaise implémentation
• S’assurer que le périmètre est suffisamment resserré pour un plan unique et cohérent

La sortie du reviewer inclut un statut Approved | Issues Found ainsi qu’une liste de problèmes, chacun associé à son impact sur la planification de l’implémentation.

3. Itérer jusqu’à approbation

Si le reviewer trouve des problèmes, mettez la spec à jour et relancez la revue. Une fois la spec approuvée, vous disposez d’une base solide pour les compétences d’implémentation et les outils de planification.

Utiliser le compagnon visuel de brainstorming

1. Démarrer le serveur du compagnon visuel

Depuis le répertoire scripts, vous pouvez démarrer le serveur de brainstorming avec :

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

Les options utiles incluent :

• --project-dir <path> – Stocker les fichiers de session sous <path>/.superpowers/brainstorm/ au lieu de /tmp pour les conserver.
• --host <bind-host> – Se lier à une interface spécifique (par exemple 0.0.0.0 dans des conteneurs ou environnements distants).
• --url-host <display-host> – Contrôler le hostname affiché dans le JSON de l’URL retournée.
• --foreground ou --background – Choisir si le serveur tourne dans le terminal actuel ou en arrière‑plan.

Au démarrage, le script affiche du JSON contenant l’URL de session. Ouvrez cette URL dans un navigateur pour accéder au frame de brainstorming visuel.

2. Générer des options visuelles

Le serveur surveille un répertoire pour des fichiers HTML et sert toujours le plus récent. Le schéma typique est :

1. Claude (ou votre agent) écrit un fichier HTML dans le screen_dir configuré en utilisant frame-template.html comme base.
2. Le navigateur se recharge automatiquement via helper.js lorsqu’un nouveau fichier est créé.
3. Les utilisateurs peuvent cliquer sur des options ou des cartes dans l’UI, et ces événements sont renvoyés via WebSocket pour être consommés par l’agent.

Cela permet de montrer facilement :

• Plusieurs options de layout sous forme de cartes cliquables
• Des diagrammes de flux et machines à états
• Des comparaisons visuelles de couleurs, d’espacements ou de variantes de composants

3. Arrêter le serveur une fois la session terminée

Quand la session est terminée, arrêtez proprement le serveur de brainstorming avec :

./stop-server.sh <session_dir>

Pour les sessions sous /tmp, cela nettoie aussi les fichiers générés. Les répertoires persistants sous .superpowers/ sont conservés, afin que vous puissiez revenir plus tard sur les maquettes et diagrammes.

Intégrer brainstorming dans votre propre workflow

• Comme étape standard avant commit : Exiger un passage par brainstorming et une spec approuvée avant de merger les branches de fonctionnalités.
• Avec d’autres compétences : Exécuter d’abord brainstorming, capturer la spec, puis transmettre à des compétences d’implémentation, de refactoring ou de test.
• Pour le travail UI/UX : Combiner le brainstorming conversationnel avec le compagnon visuel pour valider layouts et interactions avant d’écrire le moindre CSS ou code de composant.

Adaptez les chemins de dossiers, les conventions de nommage et le format des specs à vos dépôts existants tout en conservant le schéma central : contexte → questions → design/spec → revue → implémentation.

FAQ

La compétence brainstorming est‑elle réservée aux projets gros et complexes ?

Non. La compétence brainstorming est justement conçue pour éviter l’anti‑pattern « c’est trop simple pour nécessiter une conception ». Même un petit changement de config ou un utilitaire ponctuel peut cacher des hypothèses. Pour les tâches très petites, la conception peut se limiter à une description concise, mais vous devriez tout de même l’énoncer et la valider avant l’implémentation.

Puis‑je sauter l’étape brainstorming si j’ai déjà une spec ?

Si vous disposez déjà d’une spec complète, à jour et approuvée, vous n’avez pas forcément besoin d’une session brainstorming complète. En revanche, vous pouvez tout de même utiliser le modèle de reviewer contenu dans spec-document-reviewer-prompt.md pour valider cette spec avant l’implémentation. Si la revue met en lumière des lacunes ou ambiguïtés, faites un brainstorming plus court pour les combler.

Comment brainstorming s’articule‑t‑il avec les compétences d’implémentation ?

La compétence brainstorming est conçue pour être utilisée avant toute compétence d’implémentation. Elle produit :

• Une conception claire, approuvée par l’utilisateur
• Un document de spec qui peut être relu et itéré

Ce n’est qu’une fois cette validation passée que vous devriez invoquer des compétences de code ou de refactoring. Cette séparation aide à garder l’intention de conception explicite et réduit les aller‑retour pendant l’implémentation.

Dois‑je utiliser le compagnon visuel pour profiter de brainstorming ?

Non. Le compagnon visuel est optionnel.

• Si votre travail est majoritairement du backend, des APIs ou de l’infrastructure, vous pouvez utiliser brainstorming comme un workflow purement textuel.
• Si vous faites de l’UI/UX, du design produit ou du frontend, utiliser le compagnon visuel décrit dans visual-companion.md et le répertoire scripts/ facilite grandement la comparaison des options et la collecte de feedback.

Décidez en fonction de l’apport réel des visuels pour clarifier la discussion.

Que se passe‑t‑il si j’ignore le hard gate et que je commence à coder quand même ?

Ignorer le hard gate de conception fait disparaître le principal bénéfice de la compétence brainstorming : détecter les désalignements tôt. Vous risquez d’obtenir :

• Des fonctionnalités qui ne correspondent pas aux attentes des utilisateurs
• Des implémentations UI à reconstruire après feedback
• Des specs à la traîne par rapport au code, qui deviennent une dette documentaire

Considérez ce gate comme une règle de process : n’écrivez pas et ne demandez pas de code tant que la conception n’est pas rédigée, relue et explicitement approuvée.

Puis‑je personnaliser les critères de revue de spec ?

Oui. spec-document-reviewer-prompt.md définit des catégories comme l’exhaustivité, la cohérence, la clarté, le périmètre et les considérations YAGNI. Vous pouvez adapter ce modèle à votre domaine (en ajoutant par exemple des contrôles de sécurité, performance ou conformité) tout en conservant le même déroulé de revue.

Brainstorming est‑il lié à un framework ou stack technique particulier ?

Non. La compétence brainstorming est agnostique vis‑à‑vis de la stack. Elle se concentre sur la collecte de contexte, la clarification des exigences, la formulation de la conception et l’exploration visuelle, pas sur du code spécifique à un framework. Vous pouvez l’utiliser pour des apps frontend, des services backend, des intégrations ou des systèmes hybrides.

Comment désinstaller ou désactiver la compétence brainstorming ?

Cette compétence fait simplement partie du set de compétences obra/superpowers. Pour arrêter de l’utiliser, vous pouvez :

• Supprimer ou commenter sa configuration dans votre agent ou loader de compétences
• Cesser de l’appeler dans vos workflows et pipelines

La compétence brainstorming ne modifie pas votre système global ; la désactivation passe donc uniquement par la configuration et l’usage.