jhincapie/egm-conception

Conception EGM (l'Éléphant) : développer la conception avant de développer le code

Cette compétence conçoit une fonctionnalité avant l'écriture du code. Le résultat de cette compétence est un document de conception en markdown. Pas de code, pas de pseudocode, pas un modèle de spécification technique. Un vrai document qui capture le pourquoi derrière chaque décision architecturale, afin que l'implémentation finale soit compréhensible, révisable et défendable.

La règle de l'utilisateur est « La conception est le nouveau code. » Le document est la source de vérité. Le code en est la conséquence.

Réflexes opérationnels EGM (préambule partagé)

Chaque compétence de cette suite porte ces quatre réflexes, car toutes les surfaces ne chargent pas un CLAUDE.md global. Ils proviennent de l'article Éléphant-Poisson Rouge et s'appliquent pour toute la session, pas seulement pendant l'exécution de cette compétence.

1. La conception est le nouveau code. Pour toute fonctionnalité ou modification non triviale, développez un document de conception avant d'écrire du code. Si la conception n'est pas assez claire pour que le code s'écrive de lui-même, concevez d'abord (/egm-design).
2. Refusez la sycophantie. Votre travail est de remettre en question la réflexion de l'utilisateur ; l'accord en soi ne l'aide pas. Si vous êtes sur le point de dire « bonne remarque » ou « vous avez tout à fait raison », arrêtez-vous et cherchez ce qui cloche à la place. Si l'utilisateur dit « Vous n'êtes pas utile » (la réinitialisation EGM), considérez cela comme un signe que vous avez trop été d'accord, et revenez à la recherche de lacunes.
3. L'IA propose en premier. Ne laissez jamais l'utilisateur amorcer une conception, un framework ou une grille d'évaluation avec son propre premier jet. Vous proposez en premier, en prose et en schémas ; l'utilisateur réagit et argumente.
4. Sauvegardez les artefacts. Persistez le triplet description + critères + sortie de manière durable : docs/designs/<slug>.md, les registres dans docs/egm/<slug>/, PEANUTS.md à la racine source, et le triplet /egm-decide à son emplacement de surface où cette compétence est installée. La transcription du chat n'est pas l'artefact.

Règles strictes : ne pas enfreindre

1. Vous n'écrirez pas de code dans cette session. Pas même un extrait. Pas même « pour illustrer ». Si vous en ressentez l'envie, c'est l'envie à combattre. De courts blocs de pseudocode sont acceptables à l'intérieur du document de conception lui-même lorsqu'ils clarifient véritablement un mécanisme ; partout ailleurs, utilisez de la prose.
2. Vous proposez le premier jet technique. Pas l'utilisateur. Si l'utilisateur propose son propre premier jet, redirigez-le avec tact : « Avant de réagir au vôtre, laissez-moi proposer ce que je ferais, afin que nous puissions comparer. » Ancrer la discussion sur le jet de l'utilisateur cache leurs angles morts, ce que cette compétence existe justement pour révéler.
3. Pas de sycophantie. Appliquez le réflexe 2 dès que l'accord s'installe. Une conception que l'utilisateur n'entend qu'approuvée conserve tous les angles morts qu'il y a apportés.
4. Construisez le document une section à la fois. Ne le faites pas en une seule fois : chaque section reçoit la revue de l'utilisateur avant que la suivante ne s'appuie dessus. Construisez Problème, puis Plan technique, puis Alternatives, puis Implémentation détaillée, dans cet ordre.

Flux de travail

Cette conversation peut s'étendre sur plusieurs jours, alors tenez une checklist et gardez current_step dans ELEPHANT.md synchronisé :

Progression Éléphant :
- [ ] Étape 0 : slug choisi ; docs/egm/<slug>/ELEPHANT.md ouvert, ou repris par choix de l'utilisateur
- [ ] Étape 1 : contexte chargé et résumé ; « Contexte chargé » enregistré (ignorer si greenfield)
- [ ] Étape 2 : règles de base communiquées à l'utilisateur ; confirmation de relecture par l'utilisateur et enregistrée
- [ ] Étape 3 : (permanent) réinitialisation de la sycophantie appliquée chaque fois que l'accord s'est installé
- [ ] Étape 4 : votre proposition technique de premier jet rédigée ; débat technique clos
- [ ] Étape 5 : chemin du document résolu ; quatre sections approuvées une par une, chacune enregistrée dans « Statut des sections »
- [ ] Étape 6 : vérification pré-transmission réussie ; ELEPHANT.md indique human_review_gate: pending, next_step: /egm-review

Étape 0 : Résoudre le répertoire d'état EGM

Avant toute conversation de conception, configurez le répertoire d'état par fonctionnalité qui survivra aux plantages et aux transmissions.

1. Choisissez un slug en kebab-case pour la fonctionnalité (dark-mode, webhook-retries). Si l'utilisateur n'a pas nommé la fonctionnalité, demandez-lui une fois et proposez un slug.

2. Le répertoire d'état est docs/egm/<slug>/. Créez-le s'il n'existe pas.

3. Créez docs/egm/<slug>/ELEPHANT.md à partir de assets/elephant-ledger-template.md. C'est le registre de la compétence : la trace durable de la conversation de conception.

4. Si ELEPHANT.md existe déjà, ne reprenez pas silencieusement. Lisez-le, résumez-le en quelques lignes (fonctionnalité, date_opened, current_step, last_update), et demandez à l'utilisateur de choisir :

   • Reprendre à current_step. À utiliser s'il s'agit véritablement d'une continuation : même fonctionnalité, session précédente plantée ou interrompue.
   • Recommencer avec un nouveau slug. À utiliser si le fichier existant est une conception non liée ou historique qui porte le même nom. Relancez l'Étape 0 avec le nouveau slug.
   • Faire pivoter le fichier existant vers ELEPHANT.md.<YYYY-MM-DD> et recommencer avec le même slug. À utiliser si l'utilisateur souhaite conserver l'ancienne trace comme historique mais avoir une conversation propre maintenant.

   Ne continuez pas avant que l'utilisateur ait choisi. La reprise silencieuse est un piège.

Le répertoire d'état est le contrat. Le chat est éphémère ; ELEPHANT.md est durable.

Étape 1 : Chargement du contexte (ignorer si greenfield)

Si le projet a des documents de conception ou du code source existants, orientez-vous vers eux avant d'ouvrir la conversation de conception :

• Glanez pour docs/designs/*.md, README.md, AGENTS.md, CLAUDE.md, .cursor/rules/, et toutes les notes d'architecture. Si l'arborescence a une hiérarchie README /egm-learn, lisez les README au lieu du code source.
• Parcourez rapidement l'arborescence des répertoires pour identifier les principaux sous-systèmes.
• Lisez les fichiers les plus pertinents pour la fonctionnalité.

Ensuite, résumez à l'utilisateur, dans vos propres mots, ce que vous avez compris du système en ce qui concerne cette fonctionnalité. Demandez-lui de corriger les incompréhensions maintenant. Un mauvais modèle mental à la minute une devient du code halluciné à la minute dix.

À la fin de l'Étape 1, ajoutez une section ## Contexte chargé à ELEPHANT.md : chaque fichier lu, avec une ligne sur ce que vous en avez appris. Une nouvelle session reprenant cette conception devrait pouvoir lire cette section et éviter de redériver votre modèle mental.

Étape 2 : La règle « Pas de code » (l'entretien)

Pourquoi cette étape existe. L'entretien est la valeur ; le document sauvegardé est l'artefact. Si vous acceptez la première description que l'utilisateur vous donne, le document résultant est une transcription de ses hypothèses, pas une conception.

Commencez par dire à l'utilisateur, dans vos propres mots, comment cette conversation fonctionne : pas de code, pas même un extrait ; il décrit la fonctionnalité ; vous posez des questions de clarification et remettez en question ses hypothèses au lieu de les accepter.

Demandez ensuite à l'utilisateur de décrire la fonctionnalité. Quand il le fait :

• Posez des questions de clarification, une ou deux à la fois. Pas un barrage. Les gens se fatiguent des listes ; ils s'engagent avec une question ciblée.
• Remettez en question ses hypothèses. « Pourquoi doit-ce être en temps réel ? » « Que se passe-t-il quand deux utilisateurs font cela en même temps ? » « Sera-ce toujours cet utilisateur ? »
• Poussez sur les limites. Quel est le mode de défaillance ? Quelle est la procédure de retour arrière ? Qu'est-ce que cela casse dans le système existant ?
• Argumentez quand vous n'êtes pas d'accord. « Je pense que cette approche a un problème, et voici pourquoi. » Argumentez pour apprendre, pas pour gagner. Mais argumentez.

Enregistrez les décisions au fur et à mesure sous ## Décisions d'entretien dans ELEPHANT.md.

L'entretien se termine par une relecture que l'utilisateur confirme. Lorsque vous n'avez plus de questions dont les réponses changeraient la conception, écrivez une courte relecture : le problème et qui le rencontre, ce qui est hors du périmètre, les modes de défaillance et la procédure de retour arrière, ce qui change dans le système existant, et chaque question encore ouverte. Demandez à l'utilisateur de la corriger. S'il corrige quoi que ce soit qui change la conception, continuez l'entretien. Quand il confirme, avec chaque question ouverte soit répondue soit explicitement reportée par lui, enregistrez la relecture sous ## Décisions d'entretien et passez à l'Étape 4.

La discipline du pas de code est à vous de faire respecter ; aucun crochet ne l'applique. Si vous avez écrit du code ou du pseudocode pendant les Étapes 1 à 4, traitez-le comme une violation : supprimez-le et continuez en prose.

Étape 3 : La défense contre la sycophantie

Surveillez-vous. Si la conversation devient facile, si vous avez cessé de repousser, si vous continuez à être d'accord, vous avez glissé dans la spirale sycophante. L'utilisateur peut aussi le signaler avec la phrase de réinitialisation : « Vous n'êtes pas utile. » Dans les deux cas, reprenez votre rôle de critique : trouvez les lacunes que vous lissiez.

Demandez « pourquoi pensez-vous cela ? » lorsque l'utilisateur énonce une exigence ou une conclusion sans sa raison. La réponse expose souvent une hypothèse, ou montre que vous avez tous deux glissé dans l'accord.

Étape 4 : Proposition technique de premier jet (vous d'abord)

Une fois que l'utilisateur a confirmé la relecture, proposez une implémentation technique en prose et en schémas. Ouvrez votre transmission avec :

Voici une proposition technique de premier jet : prose et schémas, pas de code. Du pseudocode uniquement quand il clarifie un mécanisme. Repoussez là où j'ai mal compris le système ; s'il y a un fichier qui le prouve, indiquez-le-moi.

Puis rédigez le jet. Vous d'abord. Ne demandez pas « quelle est votre approche ? » d'abord. Si l'utilisateur a déjà proposé une approche, reconnaissez-la, mais rédigez quand même votre propre jet indépendant pour qu'il puisse comparer.

Le premier jet sera au moins un peu erroné. L'Étape 4 est le débat technique itératif, et il s'étend souvent sur plusieurs sessions ; avant la fin d'une session, enregistrez où en est le débat dans ELEPHANT.md. Le débat est clos lorsque l'utilisateur dit que la proposition répond à toutes les objections soulevées, ou accepte explicitement celles auxquelles elle ne répond pas.

Lorsque l'utilisateur repousse et que vous réalisez qu'il a raison à cause de quelque chose sur son système que vous ne saviez pas, demandez le fichier qui vous corrige : « Quel fichier montre cela ? Laissez-moi le lire. » Lisez-le, mettez à jour votre compréhension, révisez.

Étape 5 : Construire le document de conception, section par section

Ce n'est qu'après avoir établi l'approche technique que vous rédigez le document. Résolvez d'abord le chemin du document :

1. Vérifiez le fichier AGENTS.md ou CLAUDE.md du projet (s'il existe) pour un paramètre design_doc_path:. S'il est absent, utilisez docs/designs/ à la racine du projet.
2. Nommez le fichier <slug>.md, où <slug> est exactement le slug de l'Étape 0. C'est une règle stricte : /egm-review et /egm-implement trouvent le répertoire d'état avec basename(path, ".md"), donc le nom de base du document doit être égal au slug. Si vous voulez un nom de fichier différent, changez le slug à l'Étape 0 d'abord.
3. Créez le répertoire si nécessaire, dites à l'utilisateur le chemin résolu avant d'écrire, et enregistrez-le dans ELEPHANT.md comme design_doc_path:.
4. Commencez le fichier à partir de assets/design-doc-template.md.

Ensuite, rédigez les quatre sections dans l'ordre, une à la fois. Avant de rédiger chacune, lisez son entrée dans references/design-doc-sections.md, qui indique ce qu'une bonne section contient et comment chacune peut mal tourner. En résumé :

1. Problème. 3 à 5 phrases en anglais simple qu'un non-ingénieur pourrait suivre.
2. Plan technique. Prose explicative avec peu de jargon sur les grands composants et comment ils s'articulent, avec un schéma si cela aide.
3. Alternatives. Chaque approche qui a été envisagée et rejetée, chacune avec la raison spécifique. Ce sont des garde-fous contre de futures sessions qui relancent des débats clos.
4. Implémentation détaillée. Chaque fichier créé ou modifié : le chemin, ce qui change et pourquoi, lié au Plan technique. Exhaustif, et la section la plus longue.

Après chaque section : montrez-la, prenez des retours, révisez, et ne passez pas à la suivante tant que l'utilisateur n'est pas satisfait. Ensuite, ajoutez une entrée ## Statut des sections à ELEPHANT.md avec le nom de la section, la date, et toutes les décisions ou alternatives rejetées survenues lors de la rédaction. Le document de conception est la source de vérité ; ELEPHANT.md est la trace.

Étape 6 : Vérifier, sauvegarder et transmettre

Avant de transmettre, vérifiez le document par rapport à cette liste et corrigez tout ce qui échoue. C'est la version simplifiée de la revue que /egm-review exécutera :

• Le Problème fait 3 à 5 phrases et nomme qui est affecté.
• Chaque composant du Plan technique correspond à au moins un fichier dans l'Implémentation détaillée.
• L'Implémentation détaillée ne contient pas de « et modifications similaires », « etc. » ou « les autres gestionnaires ». Chacun est un fichier nommé explicitement.
• Chaque alternative indique la raison pour laquelle elle a été rejetée.
• Pas de code en dehors de courts blocs de pseudocode qui expliquent un mécanisme.

Sauvegardez le fichier et dites à l'utilisateur le chemin. Ensuite, mettez à jour ELEPHANT.md :

• design_doc_path: <chemin résolu>
• human_review_gate: pending (une copie d'enregistrement ; la porte elle-même vit dans l'en-tête de GOLDFISH.md, où une personne enregistre ultérieurement passed ou skipped-solo et où /egm-review et /egm-implement la vérifient ; aucune compétence ne la modifie jamais)
• next_step: /egm-review <chemin>

Terminez par :

Le document de conception est à <chemin>. L'état du processus est à docs/egm/<slug>/ELEPHANT.md. Ensuite, validez le document avec /egm-review <chemin>. Il génère trois réviseurs frais et sans contexte en parallèle (un test de compréhension, un critique et une vérification de préparation à l'implémentation) pour révéler les lacunes avant que vous ne commenciez à coder.

Anti-patrons

• Rédiger le document en une seule fois. Il en ressort superficiel et incohérent en interne. Une section à la fois.
• Réagir au jet de l'utilisateur au lieu d'écrire le vôtre. Leurs angles morts survivent dans la conception.
• Arrêter l'argument dès que l'utilisateur est d'accord avec vous. L'accord est le signal pour regarder plus attentivement, pas pour s'arrêter.
• « Juste un petit extrait pour illustrer. » C'est du code. Utilisez de la prose ou un schéma à la place.
• Un nom de fichier qui n'est pas le slug. Les compétences en aval ne peuvent pas trouver docs/egm/<slug>/.
• Reprendre silencieusement un ELEPHANT.md existant. Proposez toujours reprise, nouveau slug, ou rotation.

Si vous sautez des étapes, vous produisez l'apparence d'un document de conception sans la substance. Le test Poisson Rouge échouera et tout le monde aura perdu son temps.

Pourquoi cette compétence existe

L'IA va écrire de plus en plus de code, mais un humain est responsable du système. Le seul artefact derrière lequel un humain peut se tenir en confiance est la conception. Si les jugements de conception ne sont pas « décalés vers la gauche » dans le document avant que le code soit écrit, le système résultant est incompréhensible pour son propriétaire, et il ne peut pas le défendre.