Trouvez vos inconnues
Utilisez ce workflow routé pour combler l'écart entre la "carte" de l'utilisateur et le vrai "territoire" avant de prendre des décisions d'implémentation risquées. La carte est le prompt, le ticket, le plan ou la référence que l'utilisateur vous a donnée. Le territoire est le dépôt réel, le comportement du produit, le système de conception, les données, les API, les contraintes de production et les attentes tacites des utilisateurs.
Attribution : il s'agit d'un workflow d'agent original inspiré de l'article de Thariq Shihipar "A Field Guide to Fable: Finding Your Unknowns" et des exemples compagnons "Know your unknowns". Créditez le cadre lorsque vous produisez des artefacts réutilisables, mais ne copiez pas le texte source.
Politique de déclenchement
Utilisez ce workflow lorsque la tâche est vague, esthétique, stratégique, à fort enjeu, inconnue, de longue durée, dans une zone de code non inspectée, ou susceptible de cacher des contraintes produit, de conception, d'API, de sécurité, de données, de migration ou opérationnelles.
Les expressions fortes de déclenchement incluent "mieux", "plus propre", "joli", "intuitif", "prêt pour la production", "vous décidez" et "comme X". Utilisez-le également avant de créer un plan d'implémentation important, lorsque la réalité de l'implémentation contredit le plan, ou après l'implémentation pour obtenir l'adhésion du réviseur/partie prenante, une explication avant fusion, ou des workflows de compréhension des changements.
N'utilisez PAS ce workflow pour une revue de code ordinaire, une revue de bogue, une revue de sécurité ou des demandes de détection de défauts dans une PR. Ces tâches nécessitent des méthodes spécifiques à la revue, pas un routage de découverte d'inconnues. Gardez ce workflow léger ou ignorez-le complètement lorsque le changement est minuscule, évident, directement spécifié, à faible impact ou moins cher à corriger qu'à explorer.
Règles de fonctionnement
- Évitez la cérémonie pour un travail minuscule et évident. Si le changement est direct, à faible risque et bien spécifié, dites que les inconnues ont peu d'impact et procédez.
- Préférez inspecter le territoire avant de spéculer. Lisez les fichiers, tests, docs, configurations, schémas, logs ou références produit pertinents avant de présenter les risques comme des faits.
- Préférez les sondes peu coûteuses avant une implémentation irréversible. Utilisez des maquettes, des passes grep, des petits tests, des scripts jetables ou des cartes de référence avant de vous engager dans une architecture importante.
- Posez une question à fort impact à la fois lorsque l'apport de l'utilisateur est nécessaire. Priorisez les questions qui changeraient l'architecture, le modèle de données, l'UX, la posture de sécurité, la stratégie de migration, l'API publique ou le risque de mise en production.
- Produisez des artefacts concrets. Un artefact utile peut être un tableau des risques, une carte sémantique, une maquette, un registre de décisions, un fichier de notes d'implémentation, un document d'adhésion ou un quiz. Évitez les listes génériques "considérez X" sans actions suivantes.
- Continuez à travailler sauf si bloqué. Si l'utilisateur n'est pas disponible et que le risque n'est pas critique pour l'architecture/API/sécurité/données, choisissez la valeur par défaut réversible la plus conservatrice, enregistrez l'hypothèse et continuez.
Triage rapide
Classez la tâche avant de choisir un playbook :
- Connues connues : Exigences que l'utilisateur a explicitement données.
- Inconnues connues : Questions ouvertes que l'utilisateur a déjà nommées ou clairement implicites.
- Inconnues inconnues : Goût, conventions, barres de qualité et attentes du domaine que l'utilisateur reconnaîtrait une fois montrées.
- Inconnues inconnues : Contraintes cachées, comportement, risques ou connaissances manquantes du domaine que ni l'une ni l'autre partie n'a encore révélées.
Ensuite, classez l'incertitude :
- Faible incertitude, faible impact : Implémentez directement. Notez éventuellement l'hypothèse que vous avez utilisée.
- Incertitude moyenne : Exécutez un playbook ciblé et continuez.
- Incertitude élevée ou grand rayon d'impact : Inspectez le dépôt, effectuez une passe des angles morts, puis routez vers un entretien, une chasse aux références, une maquette ou un plan ajustable.
- Le plan contredit la réalité en cours de travail : Utilisez les notes d'implémentation et replanifiez la partie affectée.
- Le travail est terminé mais la compréhension ou l'adhésion manque : Utilisez un document d'adhésion ou un quiz de changement.
Table de routage
Chargez uniquement les playbooks nécessaires à la tâche en cours :
- Module de code inhabituel, contraintes cachées, ou zone à haut risque : lisez
references/blindspot-pass.md. - L'utilisateur manque de vocabulaire domaine ou de normes de qualité experte : lisez
references/teach-me-my-unknowns.md. - Conception vague, goût UX, "rends-le plus joli", "intuitif", ou "comme X" : lisez
references/design-directions.md. - La forme UX/produit est floue avant le backend, l'API ou le travail d'état : lisez
references/mock-before-wire.md. - L'espace de solution est ouvert et les compromis coût/risque comptent : lisez
references/effort-axis-brainstorm.md. - Une ambiguïté connue nécessite des décisions de l'utilisateur : lisez
references/interview.md. - Le comportement de l'implémentation existante, du produit ou du concurrent devrait être la spécification : lisez
references/reference-hunt.md. - Un grand plan est sur le point d'être fait : lisez
references/tweakable-plan.md. - L'implémentation révèle une surprise ou invalide le plan : lisez
references/implementation-notes.md. - Le travail terminé nécessite l'adhésion du réviseur ou de la partie prenante : lisez
references/buy-in-doc.md. - L'utilisateur veut comprendre un grand changement avant la fusion : lisez
references/change-quiz.md.
Workflow par défaut
- Résumez brièvement la carte : ce que l'utilisateur a demandé et ce qui est déjà connu.
- Inspectez le territoire : rassemblez les preuves de la surface produit/dépôt pertinente avant de classer les risques.
- Nommez les inconnues au plus fort impact : restez court sauf si l'utilisateur a demandé une exploration.
- Routez : choisissez un ou plusieurs playbooks de référence dans le tableau.
- Agissez : produisez l'artefact demandé, posez une question à fort impact, ou implémentez avec des hypothèses enregistrées.
Utilisez cette sortie compacte lorsqu'aucun playbook spécialisé n'est nécessaire :
Vérification des inconnues :
- Connues connues : ...
- Inconnue au plus haut risque : ...
- Sonde peu coûteuse effectuée : ...
- Hypothèse ou question : ...
- Action suivante : ...
Exemple de routage
- Module de code inhabituel : "Ajouter SSO à ce package d'authentification ; je ne l'ai pas touché avant" ->
blindspot-pass.md, puistweakable-plan.mdsi le risque est élevé. - Demande de conception vague : "Rends le tableau de bord de révision plus propre et plus premium" ->
design-directions.md, éventuellementmock-before-wire.md. - Ambiguïté architecturale connue : "Cela devrait-il résider dans la passerelle API ou le worker ?" ->
interview.md, puistweakable-plan.md. - Implémentation basée sur des références : "Porte le comportement de réessai de cette crate Rust dans notre client TypeScript" ->
reference-hunt.md. - Déviation en cours d'implémentation : "Le schéma ne supporte pas la migration planifiée" ->
implementation-notes.md, puis demandez seulement si le nouveau chemin modifie le contrat de données/API. - Quiz avant fusion : "Assure-toi que je comprends cette branche avant de fusionner" ->
change-quiz.md.