AgentDock / Trellis Brainstorm

Trellis Brainstorm

Contrat de planification non négociable

Une demande de construction, d'implémentation, de correction, de refactorisation ou de « allez-y » n'est pas une approbation pour quitter la planification. Le consentement à la création de tâche n'est pas non plus une approbation d'implémentation.

Pour toute tâche non triviale, l'utilisateur doit répondre au moins une fois après la demande initiale avant que l'implémentation ne commence. Si aucune clarification n'est nécessaire, cette réponse doit approuver le résumé de planification final décrit ci-dessous.

Tant qu'une décision appartenant à l'utilisateur concernant le produit, le périmètre, l'expérience utilisateur, la compatibilité, le risque ou l'acceptation reste non résolue, terminez le tour avec exactement une question de la plus haute valeur. Ne modifiez pas le code du produit, ne lancez pas l'implémentation et n'exécutez pas task.py start.

Règle de preuve non négociable

Si une question peut être répondue en explorant la base de code, explorez la base de code à la place.

C'est obligatoire. Avant de poser une question à l'utilisateur, vérifiez d'abord si la réponse est déjà disponible dans le code, les tests, les configurations, la documentation, les spécifications existantes ou l'historique des tâches.

Ne demandez pas à l'utilisateur de confirmer des faits que le dépôt peut fournir. Demandez uniquement l'intention produit, la préférence, le périmètre, la tolérance au risque, le comportement d'acceptation ou les décisions qui restent ambiguës après inspection.

Les preuves du dépôt établissent le comportement actuel et les contraintes techniques. Le comportement souhaité de l'utilisateur, les limites du périmètre de la fonctionnalité et les préférences UX ne sont jamais répondus par les seules preuves du dépôt, même lorsqu'un modèle existant est présent ; les modèles existants sont des options et des preuves de recommandation, pas des décisions.

---

Utilisez ce skill pendant la phase de planification 1 pour transformer la demande de l'utilisateur en exigences claires et en artefacts de planification.

Préconditions

Utilisez ce skill uniquement après que le consentement à la création de tâche a été donné et que l'utilisateur est prêt à entrer dans la planification Trellis.

Si aucune tâche n'existe encore, créez-en une :

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<titre court de la tâche>" --description "<résumé d'une ligne>" --slug <slug>)

Utilisez un titre concis issu de la demande de l'utilisateur. Le titre et --description doivent être non vides — create rejette les blancs, et un enregistrement dont l'un des deux est vide est refusé à l'archivage. Utilisez un slug sans préfixe de date. task.py create ajoute automatiquement le préfixe de répertoire MM-JJ-.

task.py create crée le fichier prd.md par défaut. Mettez à jour ce fichier avec la compréhension actuelle avant de poser des questions de suivi.

Flux de planification

1. Capturez la demande de l'utilisateur et les faits initialement connus dans prd.md.
2. Inspectez les preuves disponibles avant de poser des questions :
   • code, tests, fixtures et configurations
   • fichiers README, documentation, spécifications existantes et notes de domaine
   • tâches Trellis associées, fichiers de recherche et historique de session lorsqu'ils sont présents
3. Séparez ce que vous avez trouvé en :
   • faits confirmés
   • intention produit toujours nécessaire de la part de l'utilisateur
   • décisions de périmètre ou de risque toujours nécessaires de la part de l'utilisateur
   • éléments probablement hors périmètre
4. Si une décision appartenant à l'utilisateur reste en suspens, posez l'unique question de la plus haute valeur, incluez votre recommandation et le compromis, puis arrêtez-vous. N'effectuez pas de travail d'implémentation dans le même tour.
5. Après chaque réponse de l'utilisateur, mettez à jour prd.md, recalculez l'inventaire des décisions et répétez à partir de l'étape 2.
6. Lorsqu'aucune décision appartenant à l'utilisateur ne reste en suspens, créez ou mettez à jour design.md et implement.md pour les tâches complexes.
7. Exécutez la porte de convergence des exigences, puis la passe de convergence du PRD.
8. Présentez le résumé de planification final et arrêtez-vous. N'exécutez pas task.py start et ne modifiez pas le code du produit dans le même tour.
9. Seul un message utilisateur ultérieur qui approuve explicitement le dernier résumé de planification autorise task.py start et l'implémentation. Si les artefacts changent de manière substantielle après l'approbation, répétez la révision finale.

N'inventez pas de hiérarchie produit/spécification spécifique au projet. Si le dépôt contient déjà des documents produit, domaine ou spécification, utilisez-les. Si ce n'est pas le cas, procédez avec les preuves existantes.

Règles pour les questions

Ne posez qu'une seule question par message.

Chaque question doit inclure :

• la décision nécessaire
• pourquoi la réponse est importante
• votre réponse recommandée
• le compromis si l'utilisateur choisit différemment

Ne posez pas de questions de processus telles que demander s'il faut chercher, inspecter des fichiers ou continuer le brainstorming. Effectuez le travail de preuve directement. Demandez à l'utilisateur uniquement lorsque le problème restant est une décision produit, une préférence, une limite de périmètre ou un choix de tolérance au risque.

Les recommandations ne sont pas des sélections par défaut. Ne choisissez jamais une décision produit recommandée au nom de l'utilisateur simplement parce que l'utilisateur a demandé l'implémentation.

Ne fabriquez pas de questions de clarification lorsque la demande et les preuves du dépôt résolvent déjà chaque décision. Dans ce cas, passez directement au résumé de planification final, qui nécessite toujours une approbation explicite ultérieure.

La révision finale est une porte de transition de phase obligatoire, pas une question de processus interdite. Le consentement à la création de tâche, la demande d'implémentation initiale et l'approbation donnée avant le dernier résumé final ne satisfont pas cette porte.

Cadre de réflexion : Analyse par premiers principes

Lorsque les exigences sont vagues, les solutions semblent sur-ingéniérées ou vous êtes sur le point d'ajouter de la complexité « parce que tout le monde le fait » — décomposez les vérités fondamentales avant de raisonner vers le haut.

Étape 1 : Reformulez le problème

Dépouillez les détails d'implémentation à une phrase.

Mauvais : « Nous devons ajouter un cache Redis au point de terminaison du profil utilisateur » Bon : « Les données du profil utilisateur mettent trop de temps à charger »

Étape 2 : Listez les vérités fondamentales

Qu'est-ce qui est absolument vrai (pas une opinion ou une convention) ?

Catégorie	Exemples
Contraintes physiques	La latence réseau ≥ 0, les E/S disque ont des limites
Règles métier	« Les utilisateurs doivent voir leurs propres données »
Invariants techniques	« Les données doivent être cohérentes »
Besoins utilisateur	« L'utilisateur veut X en Y secondes »

Étape 3 : Remettez en question les hypothèses

Pour chaque composant du plan actuel :

• Fait ou convention ? « Nous utilisons toujours REST » — pourquoi ?
• Et si on supprimait cela ? Si rien ne casse, c'est inutile.
• Résout-il le problème réel ou un symptôme ? Remontez la chaîne causale.
• Qui bénéficie de cette complexité ? Si « personne », simplifiez.

Étape 4 : Construisez à partir des vérités

1. Commencez par le mécanisme minimal viable satisfaisant toutes les vérités
2. Ajoutez de la complexité uniquement lorsqu'une vérité spécifique l'exige
3. Chaque ajout doit répondre : « Quelle vérité nécessite cela ? »

Étape 5 : Validez

• La solution résout-elle le problème d'origine ?
• Quelles hypothèses doivent être vérifiées ?
• Quelle est l'expérience la plus simple pour tester cela ?

Porte de convergence des exigences

Avant la révision finale, vérifiez tout ce qui suit :

• le résultat utilisateur et la valeur produit sont explicites
• le comportement dans le périmètre et hors périmètre est explicite
• les critères d'acceptation décrivent des résultats observables
• les décisions utilisateur concernant le produit, le périmètre, l'expérience utilisateur, la compatibilité et le risque sont résolues
• les questions ouvertes bloquantes sont vides
• les inconnues techniques sont recherchées ou explicitement reportées sans modifier le comportement MVP

Les tâches légères peuvent omettre design.md et implement.md ; elles ne peuvent pas sauter l'inspection des preuves, la convergence des exigences, la révision finale ou l'approbation d'implémentation fraîche.

Le résumé de planification final doit montrer l'Objectif, le Périmètre, le Hors Périmètre, les Critères d'Acceptation, les Décisions Clés, les Risques ou Éléments Reportés pertinents, et l'état des artefacts.

Règles des artefacts

prd.md enregistre les exigences et l'acceptation :

• objectif et valeur utilisateur
• faits confirmés
• exigences
• critères d'acceptation
• hors périmètre
• questions ouvertes qui bloquent encore la planification

design.md enregistre la conception technique pour les tâches complexes :

• architecture et limites
• flux de données et contrats
• notes de compatibilité et de migration
• compromis importants
• considérations opérationnelles ou de rollback

implement.md enregistre la planification de l'exécution pour les tâches complexes :

• liste de contrôle d'implémentation ordonnée
• commandes de validation
• fichiers risqués ou points de rollback
• vérifications de suivi avant task.py start

Les tâches légères peuvent avoir uniquement prd.md. Les tâches complexes doivent avoir prd.md, design.md et implement.md avant task.py start.

implement.md ne remplace pas implement.jsonl. Dans les workflows de sous-agent, implement.jsonl et check.jsonl doivent chacun contenir au moins une entrée réelle de spécification/recherche avant task.py start ; un manifeste vide, ou contenant uniquement une ligne d'espace réservé _example héritée, ne compte pas. Les workflows en ligne contournent cette porte JSONL car la phase 2 charge le contexte via trellis-before-dev.

Passe de convergence du PRD

Avant de déclarer la planification prête ou d'exécuter task.py start, réécrivez prd.md une fois selon la structure finale décrite dans les règles des artefacts ci-dessus. Ce n'est pas un nettoyage optionnel ; c'est la porte de planification finale.

La passe doit être sans perte :

• Fusionnez les faits répétés en une seule section faisant autorité.
• Repliez les sections de brainstorming temporaires telles que « Ce que je sais déjà », « Hypothèses » et les « Questions ouvertes » résolues dans l'Objectif, le Contexte, les Exigences, les Notes Techniques ou les Critères d'Acceptation.
• Supprimez les questions ouvertes résolues au lieu de laisser des sections vides ou déjà répondues.
• Fusionnez les listes parallèles de bugs et d'exigences lorsqu'elles décrivent le même travail ; conservez la sévérité, la preuve et les ancres fichier:ligne de chaque défaut sur l'exigence propriétaire.
• Préservez chaque ancre fichier:ligne, décision, contrainte, ID d'exigence et mappage de critère d'acceptation.
• Ne passez pas à la révision finale tant qu'une question ouverte bloquante subsiste.

Après la passe, lisez prd.md de haut en bas et vérifiez qu'aucun fait n'est répété entre les sections à moins que la répétition n'ajoute de nouvelles informations.

Barre de qualité

Avant de déclarer la planification prête :

• prd.md contient des critères d'acceptation testables.
• prd.md a passé la passe de convergence du PRD : aucune section de brainstorming temporaire non résolue, aucun fait en double entre les sections, et aucune ancre, décision ou mappage d'acceptation perdu.
• Les questions pouvant être répondues par le dépôt ont déjà été répondues par inspection.
• Les questions ouvertes bloquantes sont vides.
• Les tâches complexes ont design.md et implement.md.
• Les tâches de sous-agent ont des entrées réelles sélectionnées dans implement.jsonl et check.jsonl ; les manifestes uniquement d'amorçage ne sont pas prêts.
• Le dernier résumé de planification final a été présenté à l'utilisateur.
• Dans un message ultérieur, l'utilisateur a explicitement approuvé ce résumé pour l'implémentation.

Ne commencez pas l'implémentation simplement parce que l'utilisateur a initialement demandé l'implémentation.