Story Walkthrough

Que fait Story Walkthrough ?

L'utilisateur souhaite comprendre un problème qu'il n'a pas vécu de l'intérieur. Il ne connaît ni les composants, ni le vocabulaire, ni l'ordre dans lequel les choses se produisent. Une liste de conclusions ou un résumé de diff ne l'aide pas. Une histoire, si : elle présente chaque acteur une fois, puis montre ce que chacun fait, dans l'ordre où cela se produit, jusqu'à ce que l'échec découle naturellement.

Enquêtez d'abord. L'histoire ne vaut que par les faits qui la sous-tendent. Lisez donc le code, les logs, les tickets, les documents et l'historique avant d'écrire. Si l'enquête a déjà eu lieu plus tôt dans la conversation, réutilisez-la plutôt que de la répéter.

Forme de la réponse

Ouvrez par une ligne qui pose le cadre, par exemple « Voici toute l'histoire depuis le début, sans supposer que vous connaissez le code ». Utilisez ensuite ces sections. Ignorez une section qui n'a rien de réel à dire plutôt que de la remplir.

Les personnages

Présentez chaque acteur nécessaire à l'histoire, et rien d'autre : composants, classes, messages, temporisateurs, données, et, pour un processus, les personnes, les équipes, les formulaires et les paramètres impliqués. Donnez à chacun un nom en gras et une ou deux phrases simples sur ce qu'il est et ce qu'il fait dans cette histoire.

• Nommez chaque personnage avec précision, et liez-le au code. Écrivez price_cache_key() avec un lien fichier:ligne, pas « le constructeur de clé ». Une étiquette vague fait que le lecteur s'arrête et se demande ce que cela signifie. Si un personnage s'étend sur plusieurs morceaux de code (une méthode plus les hooks du framework qui l'entourent), dites-le ici. Pour un problème hors code, liez plutôt la source : le document et l'étape, le champ du formulaire ou le chemin du paramètre.
• Choisissez une métaphore physique pour le mécanisme abstrait et gardez-la pour toute l'histoire. Par exemple, les en-têtes de message deviennent « des notes agrafées à une enveloppe », un cache devient « un tableau blanc », un verrou devient « une clé ». Introduisez la métaphore à côté du nom réel (« le cache des prix, un tableau blanc près de chaque serveur web ») pour que le lecteur puisse la relier au code. Ne changez pas de métaphore en cours de route, et n'en empilez pas deux.
• Donnez la règle que chaque personnage suit, formulée comme la propre pensée du personnage en italique : « Aujourd'hui est la date qu'indique mon horloge. » Les bugs et les pannes de processus viennent généralement de deux règles raisonnables qui s'entrechoquent, et cela rend la collision visible plus tard.

Chapitres

Racontez ce qui se produit dans l'ordre chronologique, un chapitre par étape : ## Chapitre 1 : Un acheteur regarde les prix avant minuit, ## Chapitre 2 : Les nouveaux prix arrivent, et ainsi de suite. Des titres courts qui disent ce qui se passe.

• Gardez chaque chapitre court : quelques phrases ou quelques puces.
• Mettez en gras le détail clé du chapitre, le seul fait que le lecteur ne doit pas manquer (« l'import efface le mauvais coin du tableau blanc »).
• Quand deux choses se produisent en même temps, donnez-leur leur propre chapitre et montrez les deux côtés l'un après l'autre.
• Le chapitre de l'échec cite le message d'erreur exact sous forme de citation en bloc, et dit quel code l'attrape et ce qu'il enregistre.

Pourquoi le symptôme se présente de cette façon

Après l'échec, expliquez le motif observé : pourquoi seulement les premières heures, pourquoi seulement sur certains serveurs, pourquoi seulement après un redémarrage. Reliez-le à ce que le ticket ou les logs ont réellement montré. C'est la vérification que l'histoire est juste, alors gardez-la.

Quand le problème est un risque, pas un échec

Parfois, l'histoire porte sur quelque chose qui pourrait mal tourner : un commentaire de revue, un bug latent, un « et si ». Rien n'a échoué, il n'y a donc pas de ligne de log ou de symptôme de ticket pour ancrer l'histoire. Racontez-la différemment, car un lecteur qui voit une erreur citée supposera qu'elle s'est produite.

• Dites tôt que cela ne s'est pas produit. Indiquez dans la ligne d'ouverture ou le premier chapitre qu'il s'agit d'un échec possible trouvé en lisant le code, pas d'un échec vu dans les logs ou les tests.
• Explicitez les conditions. Le chapitre de l'échec énumère exactement ce qui doit être vrai pour que l'échec se produise, sous forme de conditions numérotées (« 1. l'opération appelle un autre service après la fermeture de la portée, et 2. aucune nouvelle portée n'est ouverte autour de cet appel »). Nommez ensuite ce qui irait mal : l'assert, le type d'exception, la ligne. Ne citez pas un message d'erreur que personne n'a vu. Si vous nommez une exception, dites qu'elle vient de la lecture du code.
• Remplacez « pourquoi le symptôme se présente de cette façon » par « pourquoi rien ne l'atteint aujourd'hui ». Parcourez chaque appelant ou flux réel et montrez quelle condition il ne remplit pas, avec des liens. Cette section porte le poids de l'histoire, car le lecteur doit décider si le risque est actif.
• Cherchez les appelants que vous n'avez pas vérifiés. La rédaction de la liste « à quel point c'est grave » pour un risque est l'endroit où les chemins non vérifiés apparaissent : un appel fait en dehors de l'endroit habituel, un transport différent, une tâche en arrière-plan. Listez chacun comme non vérifié plutôt que de l'omettre, et dites quelles preuves existent (par exemple, une exécution de test propre qui l'a exercé sans le tracer).
• Comparez les coûts dans la section correctif. Un correctif pour un risque peut ramener un échec réel. Si c'est le cas, dites-le clairement : le correctif échange un risque que rien n'atteint contre un échec qui se produit.

Pourquoi cela a commencé maintenant

Si le comportement est une régression, dites ce qui a changé, quand, et pourquoi ce changement avait du sens en soi. Nommez la PR ou le commit d'abord en mots, avec l'ID entre parenthèses. Le lecteur doit savoir que le changement antérieur n'était pas négligent, seulement incomplet.

À quel point c'est grave

Listez l'impact réel : données, chiffres, alertes, bruit de log. Séparez ce qui est confirmé de ce qui est inféré, car le lecteur répétera ces affirmations à d'autres.

• Marquez chaque affirmation comme vérifiée (et comment : un test, une requête de log, un chemin de code lu de bout en bout) ou comme non vérifiée.
• N'écrivez pas « les données vont bien » à moins que quelque chose ne l'ait vérifié. Une affirmation plausible qui s'avère fausse coûte plus de confiance qu'un honnête « pas encore vérifié ».

Comment le corriger

Donnez les options de la plus petite à la plus grande (par exemple, un correctif rapide et un correctif approprié), ce que chacune change en termes d'histoire (« donnez aux deux personnages le même calendrier ») et ses limites. Terminez par une courte recommandation.

Style

• Des mots simples. Définissez chaque terme la première fois qu'il apparaît, ou omettez-le.
• Gardez les identifiants de code entre backticks à côté de la métaphore, pour que l'histoire reste traçable jusqu'au code.
• Préférez les paragraphes courts et les puces aux longs blocs.
• Suivez les règles de style d'écriture de l'utilisateur de leurs fichiers CLAUDE.md ou AGENTS.md.

Après l'histoire

Attendez-vous à des questions de suivi sur un personnage (« Alors X est le gestionnaire ? »). Répondez en ancrant le personnage au code exact : listez ce qui s'exécute, dans l'ordre, avec des liens fichier:ligne, et dites quelle partie fait ce qui importe. Si la question montre que l'histoire originale nommait quelque chose de manière vague, corrigez la dénomination dans votre réponse plutôt que de la défendre.

Exemple

references/example-stale-prices.md contient une histoire complète écrite dans ce style pour un bug de cache obsolète, plus des notes sur ce qu'elle a eu de faux. Lisez-la avant d'écrire votre première histoire dans une session, pour calibrer la longueur et le ton.