ajitta/know-your-unknowns

Boucle des inconnues — boucle opérationnelle pour travailler avec des modèles puissants

Principe fondamental : le goulot d'étranglement avec les modèles puissants n'est pas le modèle — c'est la capacité de l'utilisateur à maintenir la correspondance entre la carte (plan) et le territoire (réalité). Cet écart, ce sont les inconnues. Concevoir la boucle explorer → questionner → planifier → implémenter → journaliser les écarts → vérifier importe plus qu'un bon prompt. Origine : les 11 exemples « Connaissez vos inconnues » ; la boucle elle-même est une extension de plugin — voir skills/loop/references/talk-source.md.

Sortie : Outil Artifact → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → markdown. Chaque artefact d'étape conserve son propre contrôle de réaction ; le contrôle de la boucle lui-même est le point de contrôle par étape, qui s'assemble dans le tracker .unknowns/loop.json. Détails : skills/loop/references/output-routing.md

Étapes (10 — réduire selon la taille)

1. Définir la valeur et les critères de fin

À fixer avec l'utilisateur avant de commencer : objectif / valeur pour l'utilisateur / critères de fin / comportement existant qui ne doit jamais être cassé / coût et périmètre de modification autorisés. Sans critères de succès, le volume d'implémentation est confondu avec le progrès.

2. Investigation des angles morts → /unknowns:blindspot (ou /blindspot pour les installations copiées)

Investigation uniquement, pas d'implémentation. Trouver les inconnues inconnues, les points de conflit, les risques de régression ; produire un prompt amélioré. Si le domaine lui-même n'est pas familier (requêtes vagues car les termes sont inconnus), exécutez /unknowns:teach-me en parallèle.

3. Entretien → /unknowns:interview

Questions qui changent l'architecture d'abord, max 4 par tour.

4. Explorer les solutions et façonner (selon besoin)

• Quoi faire non décidé → /unknowns:brainstorm (carte de l'espace des solutions)
• Impossible de décrire à quoi cela devrait ressembler avec des mots → /unknowns:prototypes (maquettes divergentes)
• Possède un exemple à imiter → /unknowns:reference (analyse de référence)

5. Prototype d'hypothèse risquée (selon besoin)

Avant l'implémentation complète, construire un prototype minimal vérifiant uniquement l'hypothèse technique la plus incertaine. Énoncer d'abord l'hypothèse et les critères de succès/échec.

6. Plan → /unknowns:plan

Plan modifiable trié par probabilité de révision, pas par ordre d'exécution. Les décisions nécessitant l'avis de l'utilisateur (schémas, interfaces, contrats UX) sont en haut.

7. Implémenter + journal des écarts → appliquer les règles de /unknowns:notes

Journaliser tout ce qui n'est pas dans le plan ; s'arrêter et demander pour les décisions touchant à l'architecture, au comportement visible par l'utilisateur, aux données ou à la sécurité. Si la conversation a été compactée, réinvoquer /unknowns:notes (et ce skill pour la liste des étapes) avant de continuer l'implémentation.

8. Vérification indépendante → agent unknowns:independent-reviewer

Le lancer avec l'outil Agent (subagent_type: unknowns:independent-reviewer). Jamais un fork ou /subtask — ceux-ci héritent du contexte de l'implémenteur, ce qui est exactement ce que cette étape vise à exclure. Transmettre à l'agent : les critères de fin (étape 1), le plan approuvé (étape 6), le chemin de IMPLEMENTATION_NOTES.md, la plage de diff / les fichiers touchés, et comment exécuter les tests. Ne jamais lui transmettre le résumé de l'implémenteur.

9. Vérification de compréhension et passation → /unknowns:quiz

Vérifier que l'utilisateur peut expliquer ce travail dans une PR ou une passation. Si le travail nécessite l'approbation d'un relecteur ou d'une partie prenante, produire également un document /unknowns:buy-in.

10. Revue de valeur

Juger par la valeur réelle, pas par la qualité du code : le problème de qui a diminué et de combien / plus rapide de combien / raisons pour lesquelles cela pourrait rester inutilisé / métriques / condition de suppression. Construire est facile, générer de la valeur est encore difficile. Terminer en capturant une ligne du tableau de bord — demander à l'utilisateur si cela a révélé quelque chose qu'il ne savait pas et si cela a changé une décision, puis ajouter la ligne à .unknowns/scorecard.md. Ne jamais répondre à ces deux questions à sa place, et écrire la ligne même lorsque les deux réponses sont non. Détails : skills/loop/references/scorecard.md

Critères de réduction

• Petite correction (1–2 fichiers, spécification claire) : uniquement les règles de l'étape 7 (notes) — pas de boucle nécessaire.
• Travail moyen : 1 (un échange) → 2 → 3 → 6 → 7 → 9.
• Travail important ou non familier : toutes les étapes, avec 4 et 5 uniquement si nécessaire.
• L'étape 1 s'exécute à chaque niveau. Incertain du niveau → demander à l'utilisateur, puis enregistrer le choix.

État de la boucle (survit à la compaction, /resume, nouvelles sessions)

Conserver .unknowns/loop.json — {task, tier, stage, decisions[], artifacts[]} — et le réécrire à chaque limite d'étape. Clore chaque étape avec un point de contrôle AskUserQuestion (continuer / sauter / arrêter) et enregistrer la réponse.

• Argument status : lire le fichier ; signaler le niveau, l'étape en cours, les étapes restantes.
• Argument resume : lire le fichier ; continuer depuis l'étape enregistrée.
• Tout autre texte d'argument est la description de la tâche.
• Pas d'argument : reprendre .unknowns/loop.json s'il existe, sinon demander d'abord la tâche.

Principes opératoires (compressés)

1. Définir l'objectif. 2. Trouver les angles morts avant d'implémenter. 3. Faire poser des questions par le modèle. 4. Fournir des références et prototypes au lieu de mots. 5. Trier les plans par probabilité de révision. 6. Journaliser les inconnues et les écarts par rapport au plan. 7. Vérifier avec des tests et une revue indépendante. 8. Confirmer que l'utilisateur peut expliquer le résultat. 9. Livrables sous forme réactivable. 10. Mesurer la valeur réelle, pas le volume de code.