trace

Compétence Trace

Utilisez cette compétence pour les questions ambiguës, causales et lourdes de preuves, dont l'objectif est d'expliquer pourquoi un résultat observé s'est produit, et non de passer directement à la correction ou à la réécriture du code.

Il s'agit de la couche d'orchestration au-dessus de l'agent traceur intégré. L'objectif est de faire du traçage une piste de fonctionnement OMC réutilisable : reformuler l'observation, générer des explications concurrentes, rassembler les preuves en parallèle, classer les explications et proposer la prochaine sonde qui réduirait l'incertitude le plus rapidement.

Cas d'entrée appropriés

Utilisez /oh-my-claudecode:trace lorsque le problème est :

• ambigu
• causal
• lourd de preuves
• mieux résolu en explorant des explications concurrentes en parallèle

Exemples :

• bugs d'exécution et régressions
• comportement de performance / latence / ressources
• analyse architecturale / prémortem / postmortem
• traçage de résultats scientifiques ou expérimentaux
• explication du comportement de configuration / routage / orchestration
• « étant donné cette sortie, retracer les causes probables »

Contrat de traçage de base

Préservez toujours ces distinctions :

1. Observation — ce qui a été réellement observé
2. Hypothèses — explications concurrentes
3. Preuves pour — ce qui soutient chaque explication
4. Preuves contre / Lacunes — ce qui la contredit ou ce qui manque encore
5. Meilleure explication actuelle — l'explication principale pour l'instant
6. Inconnue critique — le fait manquant qui sépare les meilleures explications
7. Sonde discriminante — la prochaine étape la plus utile pour réduire l'incertitude

Ne vous effondrez pas vers :

• une boucle de correction générique
• un résumé de débogueur générique
• un vidage brut de la sortie d'un agent
• une certitude factice lorsque les preuves sont incomplètes

Hiérarchie de force des preuves

Traitez les preuves comme classées, non plates.

Du plus fort au plus faible :

1. Reproductions contrôlées / expériences directes / artefacts uniquement discriminants
2. Artefacts de source primaire avec provenance étroite (événements de trace, journaux, métriques, sorties de benchmarks, configurations, historique git, comportement fichier:ligne)
3. Sources indépendantes multiples convergeant vers la même explication
4. Inférence de chemin de code ou de comportement à source unique
5. Indices circonstanciels faibles (timing, nommage, ordre de pile, ressemblance avec des bugs antérieurs)
6. Intuition / analogie / spéculation

Diminuez explicitement le classement des hypothèses qui dépendent principalement des niveaux inférieurs lorsque des preuves contradictoires plus fortes existent.

Règles fortes de falsification / infirmation

Chaque série sérieuse de /trace doit tenter de falsifier sa propre explication favorite.

Pour chaque hypothèse principale :

• rassemblez les preuves pour elle
• rassemblez les preuves contre elle
• indiquez la prédiction distinctive qu'elle fait
• indiquez quelle observation serait difficile à concilier avec elle
• identifiez la sonde la moins coûteuse qui la discriminerait de la meilleure alternative

Diminuez le classement d'une hypothèse lorsque :

• des preuves directes la contredisent
• elle ne survit qu'en ajoutant de nouvelles hypothèses non vérifiées
• elle ne fait aucune prédiction distinctive par rapport aux rivales
• une alternative plus forte explique les mêmes faits avec moins d'hypothèses
• son soutien est principalement circonstanciel tandis que sa rivale a des niveaux de preuve plus forts

Forme d'orchestration en mode équipe

Utilisez le mode équipe intégré de Claude pour /trace.

Le responsable doit :

1. Reformuler précisément le résultat observé ou la question « pourquoi »
2. Extraire la cible du traçage
3. Générer plusieurs hypothèses candidates délibérément différentes
4. Lancer 3 pistes de traceurs par défaut en mode équipe
5. Assigner un agent traceur par piste
6. Demander à chaque agent traceur de rassembler les preuves pour et contre sa piste
7. Exécuter un tour de réfutation entre l'hypothèse principale et l'alternative la plus forte restante
8. Détecter si les pistes principales diffèrent réellement ou convergent vers la même cause racine
9. Fusionner les résultats en une synthèse classée avec une inconnue critique explicite et une sonde discriminante

Important : les agents doivent poursuivre des explications délibérément différentes, pas la même explication en parallèle.

Pistes d'hypothèses par défaut pour la v1

Sauf si l'invite suggère fortement une meilleure partition, utilisez ces 3 pistes par défaut :

1. Cause de chemin de code / d'implémentation
2. Cause de configuration / environnement / orchestration
3. Cause de décalage de mesure / artefact / hypothèse — couvre les défauts de méthode de vérification, pas seulement les défauts système. Exemples : la requête de vérification réutilise une clé dimensionnelle unique pour des entités, locataires, flux ou groupes distincts ; la forme du filtre de comparaison ne correspond pas au grain du schéma ; ou le nom du catalogue ou de la colonne a été supposé portable entre environnements sans énumération. Cela inclut les décalages de prémisses / d'hypothèses clés multi-entités.

Pour la piste 3, les divergences inter-entités nécessitent un audit des prémisses avant escalade : énumérez les dimensions des entités et vérifiez si un résultat de ligne zéro ou de décalage provient de l'application d'une clé sur plusieurs entités plutôt que d'un défaut système ; le résultat peut être un défaut de méthodologie de vérification.

Ces valeurs par défaut sont intentionnellement larges afin que la première tranche fonctionne aussi bien pour les bugs, la performance, l'architecture et le traçage expérimental.

Lentilles de vérification croisée obligatoires

Après le passage initial de preuves, testez la résistance des leaders avec ces lentilles lorsque pertinent :

• Lentille système -- files d'attente, tentatives, contre-pression, boucles de rétroaction, dépendances amont/aval, défaillances limites, effets de coordination
• Lentille prémortem -- supposez que la meilleure explication actuelle est incomplète ou erronée ; quel mode de défaillance embarrasserait la trace plus tard ?
• Lentille scientifique -- contrôles, facteurs de confusion, biais de mesure, variables alternatives, prédictions falsifiables

Ces lentilles ne sont pas du remplissage. Utilisez-les lorsqu'elles peuvent révéler une explication manquée, une dépendance cachée ou une inférence faible.

Contrat de l'agent

Chaque agent doit être un propriétaire de piste traceur , pas un exécuteur générique.

Chaque agent doit :

• posséder exactement une piste d'hypothèse
• reformuler explicitement son hypothèse de piste
• rassembler les preuves pour la piste
• rassembler les preuves contre la piste
• classer la force des preuves derrière son cas
• signaler les preuves manquantes, les prédictions échouées et l'incertitude restante
• nommer l'inconnue critique pour la piste
• recommander la meilleure sonde discriminante spécifique à la piste
• éviter de s'effondrer dans l'implémentation sauf instruction explicite

Les sources de preuves utiles incluent :

• code, tests, configurations, documentation, journaux, sorties et artefacts de benchmark pertinents
• artefacts de trace existants via trace_timeline
• preuves de trace agrégées existantes via trace_summary

Structure de retour recommandée pour l'agent :

1. Piste
2. Hypothèse
3. Preuves pour
4. Preuves contre / Lacunes
5. Force des preuves
6. Inconnue critique
7. Meilleure sonde discriminante
8. Confiance

Contrat de synthèse du leader

La réponse finale de /trace doit synthétiser, pas seulement concaténer.

Retournez :

1. Résultat observé
2. Hypothèses classées
3. Résumé des preuves par hypothèse
4. Preuves contre / Preuves manquantes
5. Tour de réfutation
6. Notes de convergence / séparation
7. Explication la plus probable
8. Inconnue critique
9. Sonde discriminante recommandée
10. Pistes de trace supplémentaires (facultatif, seulement si l'incertitude reste élevée)

Préservez une liste restreinte classée même si une explication est actuellement dominante.

Tour de réfutation et détection de convergence

Avant de clore la trace :

• laissez l'hypothèse non dominante la plus forte présenter sa meilleure réfutation au leader actuel
• forcez le leader à répondre à la réfutation avec des preuves, pas une affirmation
• si la réfutation affaiblit sensiblement le leader, re-classez le tableau
• si deux hypothèses « différentes » se réduisent au même mécanisme sous-jacent, fusionnez-les et dites-le explicitement
• si deux hypothèses impliquent toujours des sondes suivantes différentes, gardez-les séparées même si elles semblent similaires

Ne prétendez pas à la convergence simplement parce que plusieurs agents utilisent un langage similaire. La convergence nécessite soit :

• le même mécanisme causal racine, ou
• des flux de preuves indépendants pointant vers la même explication

Directives explicites de déclassement

Le leader doit expliquer explicitement pourquoi une hypothèse a été déclassée :

• contredite par des preuves plus fortes
• ne produit pas l'observation qu'elle prédisait
• nécessite des hypothèses ad hoc supplémentaires
• explique moins de faits que le leader
• a perdu le tour de réfutation
• a convergé vers une explication parente plus forte

Ceci est important car /trace doit apprendre au lecteur pourquoi une explication surclasse une autre, pas seulement présenter un tableau final.

Structure d'invite leader suggérée

Utilisez une invite d'orchestration orientée équipe dans ce sens :

1. « Reformulez exactement l'observation. »
2. « Générez 3 hypothèses délibérément différentes. »
3. « Créez une piste de traceur par hypothèse en utilisant le mode équipe intégré de Claude. »
4. « Pour chaque piste, rassemblez les preuves pour et contre, classez la force des preuves et nommez l'inconnue critique plus la meilleure sonde discriminante. »
5. « Appliquez les lentilles système, prémortem et scientifique aux leaders si utile. »
6. « Exécutez un tour de réfutation entre les deux meilleures explications. »
7. « Retournez un tableau d'explication classé, des notes de convergence, l'inconnue critique et la meilleure sonde discriminante unique. »

Barre de qualité de sortie

Une bonne sortie de /trace est :

• étayée par des preuves
• concise mais rigoureuse
• sceptique face à la certitude prématurée
• explicite quant aux preuves manquantes
• pratique quant à la prochaine action
• explicite quant aux raisons pour lesquelles les hypothèses plus faibles ont été déclassées

Exemple de forme de synthèse finale

Résultat observé

[Ce qui s'est passé]

Hypothèses classées

Rang	Hypothèse	Confiance	Force des preuves	Pourquoi elle mène
1	...	Élevée / Moyenne / Faible	Forte / Modérée / Faible	...

Résumé des preuves par hypothèse

• Hypothèse 1 : ...
• Hypothèse 2 : ...
• Hypothèse 3 : ...

Preuves contre / Preuves manquantes

• Hypothèse 1 : ...
• Hypothèse 2 : ...
• Hypothèse 3 : ...

Tour de réfutation

• Meilleure réfutation au leader : ...
• Pourquoi le leader a tenu / a échoué : ...

Notes de convergence / séparation

• ...

Explication la plus probable

[Meilleure explication actuelle]

Inconnue critique

[Fait manquant unique maintenant l'incertitude ouverte]

Sonde discriminante recommandée

[Prochaine sonde unique]

Pistes de trace supplémentaires

[Seulement si l'incertitude reste élevée]