Réparation Minimale HDL et Vérification de Cohérence
Un workflow pour générer le correctif sûr le plus petit afin de corriger un bug de conception HDL, puis vérifier que le correctif ne brise pas les contrats matériels ou ne laisse pas d'incohérences entre artefacts.
Ce que Couvre Cette Compétence
Cette compétence est la moitié de réparation d'un pipeline à deux compétences (localisation → réparation). Elle accepte deux chemins d'entrée :
- Avec une Note d'Hypothèse de Cause Racine (de
hdl-fault-localizationou équivalent) — analyser la note, sélectionner la meilleure hypothèse et procéder. - Avec une intention de réparation existante — lorsque l'utilisateur ou un agent précédent a déjà donné un emplacement de bug spécifique, une direction de correction, ou un diff de patch, promouvoir cette intention en hypothèse provisoire et procéder.
La compétence fait quatre choses et rien d'autre :
- Planification de correctif minimal — l'ensemble de changements le plus petit qui adresse l'hypothèse sélectionnée, sans modifications non liées.
- Scanner d'Effets de Bord — vérification des paires de contrats matériels (ready/valid, reset/flush/replay, transitions FSM, état obsolète, ordonnancement pipeline).
- Vérificateur de Liens d'Artefacts — garantir que les configs, fichiers générés, descriptions de registres et scripts de générateur restent cohérents.
- Vérification de test — exécuter la suite de tests et gérer les échecs via hypothèses de repli.
Cette compétence n'effectue PAS de localisation de faute. Si le bug n'a pas été localisé, arrêtez-vous et exigez d'abord la localisation.
Quand Utiliser Cette Compétence
Cette compétence s'active uniquement lorsque le problème a déjà été localisé. N'importe laquelle des conditions suivantes est suffisante pour entrer :
- Une Note d'Hypothèse de Cause Racine est fournie (de
hdl-fault-localizationou équivalent). - L'utilisateur ou un agent précédent a donné un emplacement de bug explicite (fichier, module, signal) et une direction de correction (quoi changer et pourquoi).
- L'utilisateur a formulé une intention de réparation claire (par exemple, "élargir ce pointeur", "ajouter un buffer de skid", "corriger la transition FSM").
- Un diff de patch existant doit être révisé pour les effets de bord ou la cohérence.
Si aucun de ces signaux d'entrée n'est présent — le bug n'est pas localisé, aucune hypothèse n'existe, et il n'y a pas d'intention de réparation spécifique à promouvoir — arrêtez-vous et exigez d'abord la localisation. N'essayez pas de diagnostiquer le bug ; c'est la responsabilité d'une compétence de localisation de faute distincte. Les demandes vagues comme "corriger ce bug", "quelque chose ne va pas", ou "mon banc de test échoue" sans aucune information de localisation ne sont PAS des signaux d'entrée — elles manquent de la spécificité requise pour le périmètre de réparation uniquement de cette compétence.
Expressions déclencheuses typiques : "appliquer le correctif", "faire le patch", "implémenter la réparation", "vérifier les effets de bord de ce patch", "vérifier les contrats matériels après ce changement", "auditer la cohérence entre artefacts".
Exigences d'Entrée
Au moins l'un des éléments suivants doit être présent avant de commencer. Si aucun n'existe, arrêtez-vous et exigez d'abord la localisation.
- Note d'Hypothèse de Cause Racine — un fichier ou texte en ligne décrivant une ou
plusieurs hypothèses, chacune avec la force des preuves et la justification. C'est l'entrée
préférée et est produite par
hdl-fault-localization. - Emplacement de bug explicite + direction de correction — l'utilisateur ou un agent précédent a identifié un fichier, module ou signal spécifique et décrit quel changement apporter. Promouvez cette intention de réparation en hypothèse provisoire.
- Intention de réparation existante — un plan formulé (par exemple, "élargir le pointeur de 4 à 5 bits") qui peut être traité comme une note à hypothèse unique.
- Diff de patch existant — une modification de code proposée à réviser pour les effets de bord et la cohérence des artefacts.
En outre, rassemblez :
- Fichiers sources pertinents — chemins vers les modules HDL, bancs de test, et code de support impliqués.
- Commande de test — la commande exacte pour exécuter la suite de tests.
- Journaux d'échec — optionnel mais recommandé pour le contexte.
Workflow Principal
Suivez ces étapes dans l'ordre. Chaque étape produit une sortie qui alimente la suivante.
Étape 0 : Vérification de la Porte d'Entrée (AVANT toute analyse de code)
Avant de lire des fichiers sources, journaux ou formes d'onde, vérifiez qu'au moins un signal d'entrée est présent dans le message de l'utilisateur. Vérifiez dans cet ordre :
- Y a-t-il une Note d'Hypothèse de Cause Racine (un chemin de fichier, YAML en ligne, ou texte structuré avec des hypothèses étiquetées et des preuves) ?
- L'utilisateur a-t-il spécifié un emplacement de bug concret et une direction de correction (un fichier, module ou signal spécifique ET une description de quel changement apporter — pas seulement "corrigez-le" ou "quelque chose ne va pas") ?
- L'utilisateur a-t-il formulé une intention de réparation spécifique (par exemple, "élargir le pointeur à 5 bits", "ajouter un buffer de skid", "changer la transition FSM de A à B") ?
- Y a-t-il un diff de patch existant à réviser ?
Si AUCUN de ces éléments n'est présent — l'utilisateur dit seulement "corrigez ce bug", "mon banc de test échoue", "quelque chose ne va pas", ou des demandes vagues similaires sans localisation — arrêtez-vous immédiatement. Ne lisez pas le code source. N'essayez pas de diagnostiquer le bug. Produisez :
Cette compétence nécessite une localisation préalable. Veuillez exécuter la localisation
de faute d'abord (hdl-fault-localization), ou fournir l'un des éléments suivants :
- Une Note d'Hypothèse de Cause Racine
- Un emplacement de bug explicite (fichier/module/signal) et une direction de correction
- Une intention de réparation spécifique (quoi changer et pourquoi)
- Un diff de patch existant à réviser
Procédez uniquement à l'Étape 1 après avoir confirmé qu'un signal d'entrée est présent.
Étape 1 : Établir l'Hypothèse de Réparation
Si une Note d'Hypothèse de Cause Racine formelle est disponible, analysez-la pour extraire :
- Chaque hypothèse, étiquetée et décrite.
- Les preuves soutenant chaque hypothèse (forte, modérée, faible).
- La direction de correction suggérée pour chaque hypothèse.
- Tout ordre de repli ou dépendance entre hypothèses.
Si la note contient plusieurs hypothèses, listez-les toutes. Si elle n'en contient qu'une, cela simplifie la sélection — mais évaluez quand même la force de ses preuves avant de vous engager.
Si aucune note d'hypothèse n'est fournie mais qu'une intention de réparation existe (emplacement de bug explicite + direction de correction, un plan de réparation formulé, ou un diff de patch existant), promouvez cette intention en hypothèse provisoire. Donnez-lui une étiquette (par exemple, "P1-sync-fifo-pointer-widen") et documentez les preuves qui la soutiennent à partir de la description de l'utilisateur. Cette hypothèse provisoire est traitée comme l'hypothèse unique pour les Étapes 2-7. N'essayez pas de générer des hypothèses alternatives ou d'effectuer une localisation de faute — le périmètre de cette compétence se termine à l'exécution de la réparation.
Étape 2 : Sélectionner la Meilleure Hypothèse à Corriger en Premier
Toutes les hypothèses ne sont pas égales. Appliquez ces critères de sélection :
- Force des preuves — privilégiez les hypothèses avec des preuves concrètes (traces de formes d'onde, motifs de journaux, conditions reproductibles) par rapport aux hypothèses spéculatives.
- Risque du correctif — privilégiez les hypothèses dont le correctif est localisé (un ou deux modules, pas de changements structurels) par rapport à celles nécessitant des réécritures étendues.
- Réversibilité — privilégiez les hypothèses dont le correctif est facile à annuler s'il ne fonctionne pas.
- Ordre de dépendance — si l'hypothèse B dépend de l'exactitude de l'hypothèse A, corrigez A en premier.
Documentez pourquoi vous avez choisi cette hypothèse plutôt que les alternatives. Si vous ne pouvez pas décider entre deux hypothèses également fortes, choisissez celle avec le risque de correctif le plus bas et notez l'autre comme repli principal.
Étape 3 : Générer un Plan de Correctif Minimal
Un "correctif minimal" ne signifie pas "modifier un seul fichier." Cela signifie : l'ensemble le plus petit de changements qui adresse correctement l'hypothèse sélectionnée, sans modifications non liées.
Pour chaque fichier que vous prévoyez de modifier, répondez :
- Pourquoi ce fichier doit-il changer ? — tracez la chaîne causale de l'hypothèse à ce changement spécifique.
- Qu'est-ce qui change exactement ? — décrivez le changement au niveau du signal/logique, pas des détails d'implémentation.
- Pourquoi est-ce le changement minimal ? — expliquez pourquoi un changement plus petit serait insuffisant ou un changement plus grand inutile.
Rejetez tout changement qui :
- Est cosmétique (formatage, renommage, mises à jour de commentaires sans lien avec le bug).
- Est un refactoring ("pendant que j'y suis, nettoyons ceci").
- Code en dur une attente de test pour faire passer un test.
- Modifie un fichier de test sans preuve que le test lui-même est erroné.
Étape 4 : Exécuter le Scanner d'Effets de Bord
Les conceptions matérielles ont des contrats implicites entre signaux. Changer un côté d'un contrat brise souvent l'autre côté. Avant d'appliquer le correctif, analysez ces violations de contrat :
paires ready/valid
Pour chaque paire de poignée de main ready/valid dans le module modifié et ses
voisins immédiats :
- Le correctif change-t-il quand
validest asserté ou désasserté ? Si oui, est-ce que la logiquereadydu consommateur fonctionne toujours correctement ? - Le correctif change-t-il quand
readyest échantillonné ou piloté ? Si oui, est-ce que la logiquevaliddu producteur a toujours du sens ? - La contre-pression est-elle toujours gérée correctement — le pipeline peut-il stagner sans perdre de données ?
reset/flush/replay
Pour chaque signal de reset, flush ou replay :
- Le correctif change-t-il quel état est effacé ou préservé sur reset ?
- Un chemin de flush draine-t-il ou invalide-t-il toujours correctement les données en vol ?
- Un chemin de replay restaure-t-il toujours l'état au point de contrôle correct ?
complétude des transitions FSM
Pour chaque machine à états finis touchée par le correctif :
- Tous les états sont-ils atteignables depuis le reset ?
- La FSM peut-elle se bloquer (pas de sortie valide d'un état) ?
- La FSM peut-elle faire une boucle infinie (boucle infinie entre états sans progression) ?
- Le correctif ajoute-t-il ou supprime-t-il des transitions d'état ? Si oui, vérifiez que la nouvelle table de transitions est complète.
état obsolète
- Le correctif introduit-il un registre ou signal qui peut contenir une valeur obsolète entre transactions ou cycles d'horloge où il devrait être effacé ?
- Le correctif repose-t-il sur un signal effacé par un mécanisme qui ne se déclenche plus correctement ?
ordonnancement pipeline
- Le correctif change-t-il l'ordre des opérations dans un pipeline ? Si oui, est-ce que les étages aval reçoivent toujours les données dans l'ordre attendu ?
- Le correctif change-t-il la profondeur du pipeline (étages ajoutés ou supprimés) ? Si oui, tous les chemins de bypass et de forwarding sont-ils ajustés ?
Documentez les résultats pour chaque catégorie, même si le résultat est "aucun problème trouvé."
Étape 5 : Exécuter le Vérificateur de Liens d'Artefacts
Les projets HDL ont souvent des fichiers de configuration, des mappages de registres et du code généré qui doivent rester synchronisés avec la source HDL. Vérifiez ces liens :
Fichiers de configuration
Analysez les fichiers de config (YAML, HJSON, JSON, TOML, INI, ou similaires) qui référencent les signaux, paramètres ou modules touchés par le correctif. Si le correctif change une valeur de paramètre, un nom de module ou une liste de ports, mettez à jour la config pour correspondre.
Fichiers générés
Vérifiez si des fichiers dans le projet sont générés automatiquement (par des générateurs de code, des scripts ou des étapes de build). Si le correctif change une source qui alimente un générateur, soit :
- Régénérez les fichiers de sortie, soit
- Signalez l'incohérence pour régénération manuelle.
Descriptions de registres
Si la conception inclut une mappe de registres (CSV, XML, IP-XACT, SystemRDL, ou similaire), vérifiez que les positions de champ de registre, largeurs et types d'accès n'ont pas dérivé par rapport au HDL après le correctif.
Scripts de générateur
Vérifiez les scripts Python, Perl, Tcl ou shell qui génèrent du HDL ou des fichiers de configuration. Si le correctif change un motif sur lequel ces scripts s'appuient (conventions de nommage, largeurs de signal, protocoles d'interface), les scripts peuvent produire une sortie cassée.
Documentez tous les artefacts vérifiés et toute incohérence trouvée.
Lorsque le correctif ne change que la logique interne (aucune interface publique, paramètres, champs de registre, mappes d'adresses, sources générées, ou comportement visible dans la configuration), la vérification des liens d'artefacts se résume à "non applicable — correctif interne uniquement sans impact entre artefacts." Évitez d'analyser l'arborescence complète du projet pour des artefacts qui ne peuvent pas être affectés par le changement. Lancez une recherche complète d'artefacts uniquement lorsque le correctif touche l'une des surfaces listées ci-dessus.
Étape 6 : Appliquer le Correctif et Exécuter les Tests
Appliquez le correctif aux fichiers sources réels. Exécutez ensuite la commande de test :
- Exécutez la suite de tests une fois.
- Si tous les tests réussissent — documentez le résultat et passez à l'Étape 7.
- Si certains tests échouent — analysez :
- Les échecs sont-ils préexistants ? Vérifiez les journaux d'échec pour voir si ces tests échouaient avant le correctif. Les échecs préexistants ne sont pas la faute du correctif — notez-les mais ne bloquez pas le correctif.
- Les échecs sont-ils causés par le correctif ? Si le correctif a introduit de nouveaux échecs, la correction est incomplète ou incorrecte. Allez au chemin de repli.
- Les échecs révèlent-ils un bug de test ? Concluez cela uniquement si vous avez des preuves concrètes que l'attente de test est erronée, pas seulement parce que le correctif a changé le comportement.
Étape 7 : Gérer l'Échec — Repli vers l'Hypothèse Suivante
Si le correctif échoue aux tests d'une manière qui est causée par le correctif (pas préexistante ou un bug de test) :
- Ne pas essayer de sauver le correctif avec des ajustements ad-hoc. Cela transforme une correction basée sur une hypothèse en devinette.
- Si l'environnement d'exécution supporte une annulation propre (par exemple,
git checkout,git stash, ou un harnais externe gérant l'état du correctif), annulez le correctif échoué avant d'essayer le repli. Si l'annulation n'est pas supportée, inspectez et défaites explicitement les modifications échouées avant de continuer — ne superposez pas un nouveau correctif sur un correctif cassé. - Sélectionnez l'hypothèse suivante dans la note d'hypothèse (celle avec la meilleure combinaison suivante de preuves et de risque).
- Documentez dans la Note de Décision de Correctif : quelle hypothèse a échoué, pourquoi (quel test a cassé), et quelle hypothèse est maintenant tentée.
- Retournez à l'Étape 2 avec l'hypothèse de repli.
Si toutes les hypothèses sont épuisées et qu'aucun correctif ne passe les tests, signalez que l'ensemble d'hypothèses est insuffisant — la cause racine peut ne pas être capturée par l'une des explications hypothétiques.
Sortie : Note de Décision de Correctif
À la fin du workflow (que le correctif ait réussi ou échoué), produisez une Note de Décision de Correctif en utilisant cette structure exacte :
patch_decision_note:
selected_hypothesis: <quel hypothèse a été corrigée>
patch_scope: <résumé en une phrase de ce que le correctif change>
modified_files:
- <chemin du fichier>: <raison pour laquelle ce fichier a dû changer>
- <chemin du fichier>: <raison pour laquelle ce fichier a dû changer>
side_effect_scan:
ready_valid: <résultat>
reset_flush_replay: <résultat>
fsm_transitions: <résultat>
stale_state: <résultat>
pipeline_ordering: <résultat>
artifact_link_check:
config_files: <résultat>
generated_files: <résultat>
register_descriptions: <résultat>
generator_scripts: <résultat>
test_results:
status: <succès/échec>
tests_passed: <nombre>
tests_failed: <nombre>
new_failures: <nombre>
pre_existing_failures: <nombre>
fallback_used: <oui/non>
fallback_hypothesis: <libellé si un repli a été utilisé>
outcome: <réussi/échec_toutes_hypothèses_épuisées>
summary: <récapitulatif en 2-3 phrases de ce qui a été fait et s'il faut
localiser davantage>
Notes sur le Périmètre
- Pas de localisation. Si le bug n'est pas localisé, arrêtez-vous. N'essayez pas de
l'être. Appelez
hdl-fault-localizationà la place. - Pas de génération de nouvelles hypothèses. Le travail de localisation doit produire toutes les hypothèses candidates. Le travail de réparation les sélectionne et les exécute.
- Pas de bricolage ad-hoc. Si un correctif échoue, revenez en arrière et réessayez avec l'hypothèse suivante. Superposer des changements ad-hoc sur un correctif échoué n'est pas autorisé.
- Vérification de cohérence. Cet outil n'est pas seulement un applicateur de correctifs — il vérifie que le correctif ne brise pas des contrats matériels implicites ou ne désynchronise pas des artefacts de conception.
- Aucun changement d'artefact partagé. Modifier des fichiers de configuration, scripts de générateur, ou descriptions de registres est dans le périmètre, mais assurez-vous que ces changements sont également minimaux et basés sur des preuves.
Compatibilité des Plateformes
Cette compétence est conçue pour une utilisation avec Claude Code, Cursor, Codex, et d'autres agents de codage IA qui prennent en charge le balisage Markdown pour les descriptions d'outils.
Considérations de Sécurité
- L'outil de correctif modifie les fichiers du projet via l'API de l'agent (lecture/écriture de fichiers), mais n'introduit pas de modifications de correctif malveillant.
- Le contenu généré par l'utilisateur est traité comme du code ; l'utilisateur est chargé d'apporter les dépendances et de préparer l'environnement.
- L'outil de test suppose que le projet a une suite de tests reproductible ; il ne modifie pas les dépendances système ni n'installe de paquets.