From 62dd242917a2ae2aadd6bb2762e033f9c2b89da7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emmanuel=20Ats=C3=A9?= <4688434+eatse21@users.noreply.github.com> Date: Thu, 21 May 2026 13:11:05 +0200 Subject: [PATCH] docs(fr): refinement of forensic-investigation --- docs/fr/explanation/forensic-investigation.md | 175 +++++++++--------- 1 file changed, 87 insertions(+), 88 deletions(-) diff --git a/docs/fr/explanation/forensic-investigation.md b/docs/fr/explanation/forensic-investigation.md index b1f02138c..71460918c 100644 --- a/docs/fr/explanation/forensic-investigation.md +++ b/docs/fr/explanation/forensic-investigation.md @@ -1,157 +1,156 @@ --- title: "Enquête de code" -description: Comment bmad-investigate traite chaque problème comme une scène d'enquête, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir +description: Comment bmad-investigate traite chaque problème comme une scène de crime, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir sidebar: order: 6 --- -Vous confiez à `bmad-investigate` un journal de plantage, une trace de pile, ou simplement un « ça marchait avant, plus -maintenant ». Le skill prend le relais avec la discipline d'enquête le temps de l'exécution. Il ne se met pas à -corriger. Il ouvre un dossier d'enquête. +Vous confiez à `bmad-investigate` un journal de plantage, une stack trace, ou simplement un « ça marchait avant, plus +maintenant ». Le skill prend le relais et applique la rigueur d’un enquêteur pendant toute son exécution. Il ne se lance pas dans +la correction. Il ouvre un dossier d’enquête. -Chaque constatation reçoit une note. Chaque hypothèse a un statut. Les fausses pistes sont conservées, pas effacées. Le -livrable est un document qu'un autre ingénieur peut reprendre à froid. +Chaque constatation est classée. Chaque hypothèse a un statut. Les fausses pistes sont conservées, pas effacées. Le +livrable est un document qu’un autre ingénieur peut reprendre à froid. -Cette page explique pourquoi l'enquête est une discipline à part entière, et ce que le skill apporte qu'un workflow de -développement classique n'apporte pas. +Cette page explique pourquoi l’enquête est une discipline à part entière, et ce que le skill apporte de plus qu’un flux de +développement classique. -## Le problème du « débogue, c'est tout » +## Le problème avec « il suffit de déboguer » Le débogage classique mélange trois activités : examiner les preuves, raisonner sur la cause, et modifier le code pour tester la théorie. Quand elles sont mélangées, deux modes de défaillance apparaissent. -Le premier est le **verrouillage narratif**[^1]. La première histoire plausible devient la théorie de travail, et chaque -observation est tordue pour la confirmer. Le bug reste non corrigé jusqu'à ce que quelqu'un abandonne et reparte de -zéro. Des heures plus tard. +Le premier est le **verrouillage narratif**[^1]. Le premier scénario plausible devient la théorie de travail, et chaque +observation est déformée pour s’y ajuster. Le bug persiste jusqu’à ce que quelqu’un abandonne et reparte de zéro. Des +heures plus tard. -Le second est l'**amnésie probatoire**. Vous avez tracé quelque chose, l'avez écarté, mais n'avez pas écrit pourquoi. -Deux jours plus tard, avec un regard frais, vous le retracez. Pire encore, un collègue reprend le bug et refait la même -impasse que vous aviez déjà éliminée. +Le second est l’**amnésie des preuves**. Vous avez suivi une piste, l’avez écartée, mais n’avez pas écrit pourquoi. Deux +jours plus tard, avec un regard frais, vous la suivez à nouveau. Pire encore, un collègue reprend le bug et suit +à nouveau la même fausse piste que vous aviez déjà écartée. La conception du skill est une réponse directe à ces deux modes. ## Classement des preuves -Chaque constatation dans une enquête appartient à l'une de trois catégories. +Chaque constatation dans une enquête appartient à l’une de trois catégories. -- **Confirmé.** Directement observé dans les logs, le code ou les dumps ; cité avec une référence spécifique (un - `chemin:ligne`, un horodatage de log, un hash de commit). Si quelqu'un demande « comment le sais-tu ? », vous pointez - la citation. +- **Confirmé.** Directement observée dans les logs, le code ou les dumps ; citée avec une référence spécifique (un + `chemin:ligne`, un horodatage de log, un hash de commit). Si quelqu’un demande « comment le savez-vous ? », vous indiquez + la référence. - **Déduit.** Découle logiquement de preuves confirmées ; la chaîne de raisonnement est explicite. Si une étape de la - chaîne est fausse, la déduction est fausse, et on peut voir précisément quelle étape. -- **Hypothétique.** Plausible mais non confirmé. Énonce quelle preuve confirmerait ou réfuterait, et déclare d'avance ce - qui le clôturerait. Les hypothèses sont explicitement *non factuelles*. + chaîne est fausse, la déduction est fausse, et on peut voir précisément laquelle. +- **Hypothétique.** Plausible mais non confirmé. Précise quelle preuve la confirmerait ou la réfuterait, et indique à + l’avance ce qui permettrait de la clore. Les hypothèses sont explicitement *des suppositions, pas des faits*. -Le classement n'est pas une posture d'humilité. Il rend le dossier lisible. Un lecteur peut parcourir la section -Confirmé pour savoir ce qui est vrai, la section Déduit pour savoir ce qui en découle, et la section Hypothétique pour -savoir ce qui reste ouvert. Confondre les trois est la première raison pour laquelle les enquêtes dérapent. +Le classement n’est pas là par modestie. Il rend le dossier lisible. Un lecteur peut parcourir la section +**Confirmé** pour savoir ce qui est vrai, la section **Déduit** pour savoir ce qui en découle, et la section **Hypothétique** pour +savoir ce qui reste ouvert. Confondre les trois est la raison la plus fréquente pour laquelle les enquêtes dérapent. -## Tête de pont d'abord +## Point d’ancrage d’abord -L'enquête ne part jamais d'une théorie. Elle part d'une seule preuve confirmée et étend la zone à partir de là. Cette -preuve peut être un message d'erreur précis, une trame de pile, ou une entrée de log horodatée. +L’enquête ne part jamais d’une théorie. Elle part d’une seule preuve confirmée et s’étend à partir de là. Cette +preuve peut être un message d’erreur précis, une stack trace, ou une entrée de log horodatée. -C'est l'inverse de la manière dont les enquêtes se déroulent souvent : quelqu'un a une intuition, construit une théorie, -puis cherche les preuves qui la soutiennent. L'intuition peut être correcte ; la *méthode* est fragile parce qu'elle -fait du biais de confirmation[^2] le comportement par défaut. +C’est l’inverse du déroulement habituel des enquêtes : quelqu’un a une intuition, construit une théorie, +puis cherche les preuves qui la soutiennent. L’intuition peut être correcte ; la *méthode* est fragile parce qu’elle +transforme le biais de confirmation[^2] en comportement par défaut. -Une tête de pont est un fait sur lequel vous pouvez revenir quand le raisonnement devient flou. Si une déduction vous -emmène quelque part d'étrange, vous pouvez remonter jusqu'à la tête de pont et essayer une autre branche. Sans elle, -vous ne savez pas quelle étape annuler. +Un point d’ancrage est un fait sur lequel vous pouvez revenir quand le raisonnement devient flou. Si une déduction vous +mène à une conclusion inattendue, vous pouvez remonter au point d’ancrage et essayer une autre branche. Sans point +d’ancrage, vous ne savez pas quelle étape annuler. -Quand les preuves sont rares, le skill le dit et bascule en exploration guidée par hypothèses : formuler des hypothèses +Quand les preuves sont rares, le skill le signale et bascule en exploration guidée par hypothèses : formuler des hypothèses à partir de ce qui est disponible, identifier ce qui testerait chacune, présenter une liste priorisée de données à -collecter. L'absence de preuve est elle-même une constatation. +collecter. L’absence de preuve est elle-même un constat. ## Discipline des hypothèses Les hypothèses ne sont jamais supprimées du dossier. Quand une preuve en confirme ou en réfute une, son champ **Statut** -passe d'Ouvert à Confirmé ou Réfuté, et une **Résolution** explique quelle preuve a tranché. +passe d’Ouvert à Confirmé ou Réfuté, et une **Résolution** explique quelle preuve a tranché. -Cette règle a un coût réel : les dossiers grossissent. Le bénéfice est réel aussi. L'historique complet du raisonnement +Cette règle a un coût réel : les dossiers grossissent. Le bénéfice est tout aussi réel. L’historique complet du raisonnement fait partie du livrable. Six mois plus tard, quand un bug similaire surgit, le prochain enquêteur peut lire le dossier -original et voir quelles pistes ont déjà été éliminées et pourquoi. Sans cet historique, chaque nouvel enquêteur refait -les mêmes impasses. +original et voir quelles pistes ont déjà été éliminées et pourquoi. Sans cet historique, chaque nouvel enquêteur reprend +les mêmes fausses pistes. -Cela discipline aussi l'enquêteur du présent. Si vous ne pouvez pas supprimer une hypothèse fausse, vous devez la -réfuter avec une preuve citée. L'abandonner discrètement quand elle devient gênante n'est plus une option. +Cela discipline aussi l’enquêteur sur le moment. Si vous ne pouvez pas supprimer une hypothèse fausse, vous devez la +réfuter avec une preuve citée. L’abandonner discrètement quand elle devient gênante n’est plus une option. ## Remettre en question la prémisse -La description du problème par l'utilisateur est une hypothèse, pas un fait. « Le cache est cassé » est quelque chose -que l'utilisateur *croit*. Avant que le skill ne construise une enquête autour, les affirmations techniques sont -vérifiées de manière indépendante. Si la preuve contredit la prémisse, le rapport le dit directement. +La description du problème par l’utilisateur est une hypothèse, pas un fait. « Le cache est cassé » est ce +que l’utilisateur *croit*. Avant que le skill ne construise une enquête autour de cette prémisse, les affirmations +techniques sont vérifiées de manière indépendante. Si la preuve contredit la prémisse, le rapport le signale sans détour. -C'est l'instinct de l'enquêteur : le récit du témoin est une donnée, pas la vérité. Parfois le bug rapporté est réel -mais mal étiqueté. Parfois le symptôme décrit est en aval d'une cause différente. Les enquêtes qui prennent la prémisse -pour argent comptant diagnostiquent le mauvais défaut, et le bug revient sous une forme légèrement différente. +C’est l’instinct de l’enquêteur : le récit du témoin est une donnée, pas la vérité. Parfois le bug rapporté est réel +mais mal étiqueté. Parfois le symptôme décrit est en aval d’une cause différente. Les enquêtes qui prennent la prémisse +pour argent comptant diagnostiquent le mauvais problème, et le bug revient sous une forme légèrement différente. -## Une marche calibrée +## Une approche calibrée -Le skill est une seule procédure, pas deux modes. Il calibre la part d'investigation de défaut versus la part -d'exploration de zone que l'entrée demande, sur une échelle continue. +Le skill est une seule procédure, pas deux modes. Il ajuste en continu l’équilibre entre la recherche du défaut et l’exploration du code +environnant, selon ce que le cas requiert. -Un cas piloté par symptôme (un ticket, un plantage, un message d'erreur, un « ça marchait avant ») penche vers le suivi -d'hypothèses, la reconstruction de la chronologie et une direction de correction. Un cas sans symptôme (comprendre un +Un cas orienté symptôme (un ticket, un plantage, un message d’erreur, un « ça marchait avant ») penche vers le suivi +d’hypothèses, la reconstruction de la chronologie et une piste de correction. Un cas sans symptôme (comprendre un module avant de le toucher, évaluer la réutilisabilité, bâtir un modèle mental) penche vers la cartographie entrées/sorties, le filtrage du flux de contrôle et un plan de vérification. La plupart des cas réels se situent quelque -part entre les deux, et le dossier reflète l'équilibre que les preuves ont exigé. +part entre les deux, et le dossier reflète l’équilibre que les preuves ont exigé. -La discipline est la même quel que soit l'endroit de l'échelle où se situe un cas : tête de pont d'abord, classement -des preuves, suivi des hypothèses, jamais effacer. La sortie est toujours -`{implementation_artifacts}/investigations/{slug}-investigation.md`, avec les sections qui ne s'appliquent pas à un cas -laissées vides ou omises. +La discipline est la même quel que soit le positionnement du cas sur l’échelle : point d’ancrage d’abord, classement +des preuves, suivi des hypothèses, rien n’est jamais effacé. La sortie est toujours +`{implementation_artifacts}/investigations/{slug}-investigation.md`, les sections non +pertinentes étant laissées vides ou omises. -Quand un bug profond exige de comprendre un sous-système plus large, la procédure intègre en ligne les techniques de +Quand un bug profond exige de comprendre un sous-système plus large, la procédure intègre directement les techniques de cartographie entrées/sorties, de filtrage du flux de contrôle, de raisonnement à rebours depuis les sorties et de -traçage des frontières inter-composants[^3]. Le modèle de la zone atterrit dans le même dossier. Pas de changement de +traçage des frontières inter-composants[^3]. La modélisation de la zone explorée figure dans le même dossier. Pas de changement de mode. -## La méthodologie vit dans le skill +## La méthodologie réside dans le skill -La discipline d'enquête est une propriété du skill lui-même. Quiconque invoque `bmad-investigate` adopte la méthodologie -et le style de communication pour l'exécution : précision clinique, langage centré sur la preuve, pas de prudence -inutile, présentation en dossier de cas. Quand le skill se termine, l'appelant retrouve sa voix d'avant. Pas de -changement de persona, juste un déplacement de ton issu des principes du skill. +La discipline d’enquête est une propriété du skill lui-même. Quiconque invoque `bmad-investigate` adopte la méthodologie +et le style de communication pendant l’exécution : précision clinique, langage centré sur la preuve, pas de prudence +inutile, structuration en dossier d’enquête. Quand le skill se termine, l’appelant retrouve sa voix habituelle. Pas de +changement de persona, juste un ajustement de ton dicté par les principes du skill. -Cela compte parce que l'enquête et l'implémentation récompensent des instincts différents. Les enquêteurs sont lents et -précis. Les implémenteurs sont rapides et confiants. Le même cerveau faisant les deux dans une seule session finit par -mal faire les deux. Le skill délimite la posture d'enquête en ligne, sans changement de contexte vers une identité -séparée. +C’est important car l’enquête et l’implémentation sollicitent des réflexes différents. Les enquêteurs sont lents et +précis. Les développeurs sont rapides et confiants. Essayer de faire les deux dans une même session finit +généralement par mal faire l’un et l’autre. Le skill délimite la posture d’enquête directement dans le flux de travail, sans basculer dans une +identité distincte. ## Ce que vous obtenez -Un fichier d'enquête achevé : +Un dossier d’enquête complet : -- Sépare les constatations Confirmées (avec citations) des Déductions et des Hypothèses -- Préserve toutes les hypothèses jamais formulées, avec leur Statut final et leur Résolution +- Sépare les constatations **Confirmées** (avec citations) des **Déductions** et des **Hypothèses** +- Préserve l’intégralité des hypothèses formulées, avec leur Statut final et leur Résolution - Reconstruit une chronologie des événements à partir de plusieurs sources de preuves -- Identifie les lacunes de données et ce qu'elles résoudraient -- Fournit des conclusions actionnables ancrées dans les preuves +- Identifie les lacunes de données et ce qu’elles permettraient de résoudre +- Fournit des conclusions exploitables ancrées dans les preuves - Inclut un plan de reproduction quand une cause racine est identifiée -- Maintient un backlog d'enquête de pistes encore à explorer +- Maintient un backlog des pistes restant à explorer -Donnez-le à un ingénieur qui n'était pas là, et il comprend ce qui s'est passé, ce qui est connu, et ce qui reste -incertain. C'est la barre. +Transmettez-le à un ingénieur qui n’était pas là, et il comprendra ce qui s’est passé, ce qui est connu, et ce qui reste +incertain. C’est le standard visé. -## L'idée plus large +## La vision d’ensemble -La plupart du « débogage par IA » d'aujourd'hui mélange preuves, raisonnement et changements de code en un seul flux de -texte plausible. Le signal est difficile à trouver, les impasses se répètent, et le dossier, s'il en existe un, est un -journal de chat que personne ne veut lire. +La plupart des approches de « débogage par IA » actuelles mêlent preuves, raisonnement et changements de code en un seul +flux de texte plausible. Le signal est difficile à trouver, les impasses se répètent, et le dossier, s’il en existe un, est +un historique de conversation que personne ne veut lire. -`bmad-investigate` traite l'enquête comme une discipline avec son propre livrable. La preuve a une note. Les hypothèses -ont un statut. Les fausses pistes sont documentées, pas effacées. Le dossier survit à la session. +`bmad-investigate` traite l’enquête comme une discipline avec son propre livrable. Chaque preuve est classée. Les +hypothèses ont un statut. Les fausses pistes sont documentées, pas effacées. Le dossier survit à la session. -Quand le prochain bug ressemblant à un que vous avez déjà vu apparaîtra, vous aurez un point de départ qui ne sera pas -une invite vide. +Quand un bug similaire réapparaîtra, vous aurez un point de départ concret, pas un prompt vide. ## Glossaire [^1]: **Verrouillage narratif** : phénomène cognitif par lequel un raisonnement adopte la première explication plausible -et l'enrichit progressivement, devenant de plus en plus difficile à abandonner même face à des preuves contraires. +et l’enrichit progressivement, devenant de plus en plus difficile à abandonner même face à des preuves contraires. [^2]: **Biais de confirmation** : tendance cognitive à rechercher, interpréter et favoriser les informations qui confirment des croyances préexistantes, tout en ignorant ou minimisant celles qui les contredisent. -[^3]: **Passage de frontière** : transition entre deux zones d'exécution distinctes (langage, processus, machine, -client/serveur, code/configuration). Les frontières concentrent les bugs car chaque côté suppose que l'autre s'est +[^3]: **Passage de frontière** : transition entre deux zones d’exécution distinctes (langage, processus, machine, +client/serveur, code/configuration). Les frontières concentrent les bugs car chaque côté suppose que l’autre s’est comporté comme documenté.