Minimale HDL-Reparatur und Konsistenzprüfung

Ein Workflow zur Erstellung des kleinstmöglichen sicheren Patches zur Behebung eines HDL-Designfehlers, um sicherzustellen, dass die Korrektur weder Hardware-Verträge verletzt noch Inkonsistenzen zwischen verschiedenen Artefakten hinterlässt.

Was dieser Skill abdeckt

Dieser Skill ist die Reparaturhälfte einer zweistufigen Pipeline (Lokalisierung → Reparatur). Er akzeptiert zwei Einstiegspfade:

Mit einer Notiz zur Ursachenhypothese (aus hdl-fault-localization oder einem Äquivalent) — die Notiz analysieren, die beste Hypothese auswählen und fortfahren.
Mit einer bestehenden Reparaturabsicht — wenn der Benutzer oder ein vorheriger Agent bereits einen bestimmten Fehlerort, eine Korrekturrichtung oder einen Patch-Diff angegeben hat, diese Absicht zu einer vorläufigen Hypothese erheben und fortfahren.

Der Skill führt vier Dinge aus und sonst nichts:

Minimale Patch-Planung — die kleinste Menge an Änderungen, die die ausgewählte Hypothese adressiert, ohne unnötige Modifikationen.
Nebenwirkungs-Scanner — Überprüfung von Hardware-Vertragspaaren (ready/valid, reset/flush/replay, FSM-Übergänge, veralteter Zustand, Pipeline-Reihenfolge).
Artefakt-Verknüpfungsprüfer — Sicherstellen, dass Konfigurationen, generierte Dateien, Registerbeschreibungen und Generatorskripte konsistent bleiben.
Testverifikation — Ausführen der Testsuite und Behandlung von Fehlern durch Ausweichhypothesen.

Dieser Skill führt KEINE Fehlerlokalisierung durch. Wenn der Fehler nicht lokalisiert wurde, anhalten und zuerst eine Lokalisierung anfordern.

Wann dieser Skill verwendet wird

Dieser Skill wird nur aktiviert, wenn das Problem bereits lokalisiert wurde. Jeder der folgenden Punkte ist ausreichend, um einzusteigen:

Eine Notiz zur Ursachenhypothese liegt vor (aus hdl-fault-localization oder einem Äquivalent).
Der Benutzer oder ein vorheriger Agent hat einen expliziten Fehlerort (Datei, Modul, Signal) und eine Korrekturrichtung (was geändert werden soll und warum) angegeben.
Der Benutzer hat eine klare Reparaturabsicht geäußert (z. B. „diesen Zeiger verbreitern“, „einen Skid-Puffer hinzufügen“, „den FSM-Übergang korrigieren“).
Ein vorhandener Patch-Diff muss auf Nebenwirkungen oder Konsistenz überprüft werden.

Wenn keins dieser Einstiegssignale vorhanden ist — der Fehler nicht lokalisiert wurde, keine Hypothese existiert und keine spezifische Reparaturabsicht zur Erhebung vorliegt — anhalten und zuerst eine Lokalisierung anfordern. Versuchen Sie nicht, den Fehler zu diagnostizieren; das ist die Aufgabe eines separaten Skills zur Fehlerlokalisierung. Vage Anfragen wie „diesen Fehler beheben“, „etwas stimmt nicht“ oder „meine Testbench schlägt fehl“ ohne Lokalisierungsinformationen sind KEINE Einstiegssignale — ihnen fehlt die Spezifität, die für den auf Reparatur beschränkten Umfang dieses Skills erforderlich ist.

Typische Auslösephrasen: „die Korrektur anwenden“, „den Patch erstellen“, „die Reparatur implementieren“, „diesen Patch auf Nebenwirkungen prüfen“, „Hardware-Verträge nach dieser Änderung überprüfen“, „Artefakt-Konsistenz prüfen“.

Eingabeanforderungen

Mindestens eine der folgenden Bedingungen muss vor dem Start erfüllt sein. Wenn keine existiert, anhalten und zuerst eine Lokalisierung anfordern.

Notiz zur Ursachenhypothese — eine Datei oder Inline-Text, der eine oder mehrere Hypothesen beschreibt, jeweils mit Beweisstärke und Begründung. Dies ist die bevorzugte Eingabe und wird von hdl-fault-localization erzeugt.
Expliziter Fehlerort + Korrekturrichtung — der Benutzer oder ein vorheriger Agent hat eine bestimmte Datei, ein Modul oder Signal identifiziert und beschrieben, welche Änderung vorgenommen werden soll. Diese Reparaturabsicht zu einer vorläufigen Hypothese erheben.
Bestehende Reparaturabsicht — ein erklärter Plan (z. B. „den Zeiger von 4 auf 5 Bit verbreitern“), der als Notiz mit einer einzigen Hypothese behandelt werden kann.
Vorhandener Patch-Diff — eine vorgeschlagene Code-Änderung zur Überprüfung auf Nebenwirkungen und Artefaktkonsistenz.

Zusätzlich sammeln:

Relevante Quelldateien — Pfade zu den beteiligten HDL-Modulen, Testbenches und unterstützendem Code.
Testbefehl — der genaue Befehl zum Ausführen der Testsuite.
Fehlerprotokolle — optional, aber für den Kontext empfohlen.

Kernworkflow

Führen Sie die folgenden Schritte in dieser Reihenfolge aus. Jeder Schritt erzeugt eine Ausgabe, die in den nächsten Schritt einfließt.

Schritt 0: Einstiegsprüfung (VOR jeder Code-Analyse)

Bevor Sie Quelldateien, Protokolle oder Wellenformen lesen, überprüfen Sie, ob mindestens ein Einstiegssignal in der Nachricht des Benutzers vorhanden ist. Prüfen Sie in dieser Reihenfolge:

Liegt eine Notiz zur Ursachenhypothese vor (ein Dateipfad, Inline-YAML oder strukturierter Text mit gekennzeichneten Hypothesen und Beweisen)?
Hat der Benutzer einen konkreten Fehlerort und eine Korrekturrichtung angegeben (eine bestimmte Datei, ein Modul oder Signal UND eine Beschreibung, welche Änderung vorgenommen werden soll — nicht nur „beheben“ oder „etwas stimmt nicht“)?
Hat der Benutzer eine spezifische Reparaturabsicht geäußert (z. B. „den Zeiger auf 5 Bit verbreitern“, „einen Skid-Puffer hinzufügen“, „den FSM-Übergang von A nach B ändern“)?
Liegt ein vorhandener Patch-Diff zur Überprüfung vor?

Wenn KEINE dieser Bedingungen erfüllt ist — der Benutzer sagt nur „diesen Fehler beheben“, „meine Testbench schlägt fehl“, „etwas stimmt nicht“ oder ähnliche vage Anfragen ohne Lokalisierung — sofort anhalten. Lesen Sie keinen Quellcode. Versuchen Sie nicht, den Fehler zu diagnostizieren. Ausgeben:

Dieser Skill erfordert eine vorherige Lokalisierung. Bitte führen Sie zuerst die
Fehlerlokalisierung durch (hdl-fault-localization), oder geben Sie einen der folgenden Punkte an:
- Eine Notiz zur Ursachenhypothese
- Einen expliziten Fehlerort (Datei/Modul/Signal) und Korrekturrichtung
- Eine spezifische Reparaturabsicht (was zu ändern ist und warum)
- Einen vorhandenen Patch-Diff zur Überprüfung

Fahren Sie erst mit Schritt 1 fort, nachdem Sie bestätigt haben, dass ein Einstiegssignal vorhanden ist.

Schritt 1: Reparaturhypothese aufstellen

Wenn eine formelle Notiz zur Ursachenhypothese verfügbar ist, analysieren Sie sie, um zu extrahieren:

Jede Hypothese, gekennzeichnet und beschrieben.
Die Beweise, die jede Hypothese stützen (stark, moderat, schwach).
Die vorgeschlagene Korrekturrichtung für jede Hypothese.
Jede Ausweich-Reihenfolge oder Abhängigkeit zwischen Hypothesen.

Wenn die Notiz mehrere Hypothesen enthält, listen Sie alle auf. Wenn sie nur eine enthält, vereinfacht dies die Auswahl — bewerten Sie aber trotzdem ihre Beweisstärke, bevor Sie sich festlegen.

Wenn keine Hypothesennotiz bereitgestellt wird, aber eine Reparaturabsicht vorliegt (expliziter Fehlerort

Korrekturrichtung, ein erklärter Reparaturplan oder ein vorhandener Patch-Diff), erheben Sie diese Absicht zu einer vorläufigen Hypothese. Geben Sie ihr eine Bezeichnung (z. B. „P1-sync-fifo-pointer-widen“) und dokumentieren Sie die Beweise, die sie aus der Beschreibung des Benutzers stützen. Diese vorläufige Hypothese wird als einzige Hypothese für die Schritte 2-7 behandelt. Versuchen Sie nicht, alternative Hypothesen zu generieren oder eine Fehlerlokalisierung durchzuführen — der Umfang dieses Skills endet mit der Ausführung der Reparatur.

Schritt 2: Beste Hypothese zum ersten Patchen auswählen

Nicht alle Hypothesen sind gleich. Wenden Sie diese Auswahlkriterien an:

Beweisstärke — Hypothesen mit konkreten Beweisen bevorzugen (Wellenform- Spuren, Protokollmuster, reproduzierbare Bedingungen) gegenüber spekulativen. 2.Patch-Risiko — Hypothesen bevorzugen, deren Korrektur lokalisiert ist (ein oder zwei Module, keine strukturellen Änderungen) gegenüber solchen, die umfangreiche Umschreibungen erfordern.
Umkehrbarkeit — Hypothesen bevorzugen, deren Patch leicht rückgängig gemacht werden kann, falls er nicht funktioniert.
Abhängigkeitsreihenfolge — wenn Hypothese B davon abhängt, dass Hypothese A korrekt ist, zuerst A patchen.

Dokumentieren Sie, warum Sie diese Hypothese gegenüber den Alternativen ausgewählt haben. Wenn Sie sich nicht zwischen zwei gleich starken Hypothesen entscheiden können, wählen Sie die mit dem geringeren Patch-Risiko und notieren Sie die andere als primäre Ausweichhypothese.

Schritt 3: Minimalen Patch-Plan generieren

Ein „minimaler Patch“ bedeutet nicht „nur eine Datei ändern“. Es bedeutet: die kleinste Menge von Änderungen, die die ausgewählte Hypothese korrekt adressiert, ohne unnötige Modifikationen.

Für jede Datei, die Sie ändern möchten, antworten Sie:

Warum muss sich diese Datei ändern? — verfolgen Sie die kausale Kette von der Hypothese zu dieser spezifischen Änderung.
Was ändert sich genau? — beschreiben Sie die Änderung auf Signal-/Logik-Ebene, nicht auf Implementierungsdetails.
Warum ist dies die minimale Änderung? — erklären Sie, warum eine kleinere Änderung unzureichend oder eine größere Änderung unnötig wäre.

Jede Änderung ablehnen, die:

Kosmetisch ist (Formatierung, Umbenennung, Kommentaraktualisierungen, die nichts mit dem Fehler zu tun haben).
Eine Refaktorisierung ist („während ich schon dabei bin, lasse ich mich hier aufräumen“).
Eine Testerwartung hartkodiert, um einen Test bestehen zu lassen.
Eine Testdatei ändert, ohne Beweise, dass der Test selbst falsch ist.

Schritt 4: Nebenwirkungs-Scanner ausführen

Hardware-Designs haben implizite Verträge zwischen Signalen. Das Ändern einer Seite eines Vertrags bricht oft die andere Seite. Bevor Sie den Patch anwenden, scannen Sie nach diesen Vertragsverletzungen:

ready/valid-Paare

Für jedes ready/valid-Handshake-Paar im geänderten Modul und seinen direkten Nachbarn:

Ändert der Patch, wann valid aktiviert oder deaktiviert wird? Wenn ja, funktioniert die ready-Logik des Verbrauchers dann noch korrekt?
Ändert der Patch, wann ready abgetastet oder getrieben wird? Wenn ja, ist die valid-Logik des Erzeugers dann noch sinnvoll?
Wird der Rückstau noch korrekt behandelt? Kann die Pipeline anhalten, ohne Daten zu verlieren?

reset/flush/replay

Für jedes Reset-, Flush- oder Replay-Signal:

Ändert der Patch, welcher Zustand beim Reset gelöscht oder beibehalten wird?
Leert oder invalidiert ein Flush-Pfad immer noch korrekt in-flight-Daten?
Stellt ein Replay-Pfad immer noch den Zustand auf den richtigen Prüfpunkt wieder her?

Vollständigkeit der FSM-Übergänge

Für jeden endlichen Automaten (FSM), der vom Patch betroffen ist:

Sind alle Zustände vom Reset aus erreichbar?
Kann die FSM in einen Deadlock geraten (kein gültiger Ausgang aus einem Zustand)?
Kann die FSM in einen Livelock geraten (Endlosschleife zwischen Zuständen ohne Fortschritt)?
Fügt der Patch Zustandsübergänge hinzu oder entfernt er welche? Wenn ja, überprüfen Sie die neue Übergangstabelle auf Vollständigkeit.

veralteter Zustand (stale state)

Führt der Patch ein Register oder Signal ein, das über Transaktionen oder Taktzyklen hinweg einen veralteten Wert halten kann, wo es gelöscht werden sollte?
Verlässt sich der Patch auf ein Signal, das durch einen Mechanismus gelöscht wird, der nicht mehr korrekt auslöst?

Pipeline-Reihenfolge

Ändert der Patch die Reihenfolge der Operationen in einer Pipeline? Wenn ja, erhalten nachgelagerte Stufen die Daten noch in der erwarteten Reihenfolge?
Ändert der Patch die Pipeline-Tiefe (Stufen hinzugefügt oder entfernt)? Wenn ja, sind alle Bypass- und Forwarding-Pfade angepasst?

Dokumentieren Sie die Ergebnisse für jede Kategorie, auch wenn das Ergebnis „keine Probleme gefunden“ ist.

Schritt 5: Artefakt-Verknüpfungsprüfer ausführen

HDL-Projekte haben oft Konfigurationsdateien, Registerkarten und generierten Code, die mit der HDL-Quelle synchronisiert bleiben müssen. Überprüfen Sie diese Verknüpfungen:

Konfigurationsdateien

Scannen Sie nach Konfigurationsdateien (YAML, HJSON, JSON, TOML, INI oder ähnlich), die auf die Signale, Parameter oder Module verweisen, die vom Patch betroffen sind. Wenn der Patch einen Parameterwert, Modulnamen oder eine Portliste ändert, aktualisieren Sie die Konfiguration entsprechend.

Generierte Dateien

Prüfen Sie, ob Dateien im Projekt automatisch generiert werden (durch Code-Generatoren, Skripte oder Build-Schritte). Wenn der Patch eine Quelle ändert, die einen Generator speist, entweder:

Die Ausgabedateien neu generieren, oder
Die Inkonsistenz für eine manuelle Neugenerierung kennzeichnen.

Registerbeschreibungen

Wenn das Design eine Registerkarte (CSV, XML, IP-XACT, SystemRDL oder ähnlich) enthält, überprüfen Sie, ob die Registerfeldpositionen, -breiten und Zugriffstypen nach dem Patch vom HDL abweichen.

Generatorskripte

Überprüfen Sie Python-, Perl-, Tcl- oder Shell-Skripte, die HDL- oder Konfigurationsdateien generieren. Wenn der Patch ein Muster ändert, auf das diese Skripte angewiesen sind (Namenskonventionen, Signalbreiten, Schnittstellenprotokolle), können die Skripte fehlerhafte Ausgabe erzeugen.

Dokumentieren Sie alle überprüften Artefakte und alle gefundenen Inkonsistenzen.

Wenn der Patch nur interne Logik ändert (keine öffentlichen Schnittstellen, Parameter, Registerfelder, Adresskarten, generierte Quellen oder konfigurationssichtbares Verhalten), reduziert sich die Artefakt-Verknüpfungsprüfung auf „nicht anwendbar — interner Patch ohne Auswirkungen auf andere Artefakte.“ Vermeiden Sie es, den gesamten Projektbaum nach Artefakten zu durchsuchen, die von der Änderung nicht betroffen sein können. Führen Sie eine vollständige Artefaktsuche nur durch, wenn der Patch eine der oben aufgeführten Oberflächen berührt.

Schritt 6: Patch anwenden und Tests ausführen

Wenden Sie den Patch auf die tatsächlichen Quelldateien an. Führen Sie dann den Testbefehl aus:

Führen Sie die Testsuite einmal aus.
Wenn alle Tests bestanden werden — dokumentieren Sie das Ergebnis und fahren Sie mit Schritt 7 fort.
Wenn einige Tests fehlschlagen — analysieren Sie:
- Sind die Fehler bereits vorhanden? Überprüfen Sie die Fehlerprotokolle, ob diese Tests bereits vor dem Patch fehlgeschlagen sind. Bereits vorhandene Fehler sind nicht die Schuld des Patches — notieren Sie sie, blockieren Sie aber nicht die Korrektur.
- Werden die Fehler durch den Patch verursacht? Wenn der Patch neue Fehler eingeführt hat, ist die Korrektur unvollständig oder falsch. Gehen Sie zum Ausweichpfad.
- Zeigen die Fehler einen Testfehler auf? Ziehen Sie diese Schlussfolgerung nur, wenn Sie konkrete Beweise haben, dass die Testerwartung falsch ist, nicht nur, weil der Patch das Verhalten geändert hat.

Schritt 7: Fehlerbehandlung — Ausweichhypothese

Wenn der Patch Tests fehlschlagen lässt, die durch den Patch verursacht wurden (nicht bereits vorhanden oder Testfehler):

Versuchen Sie nicht, den Patch mit Ad-hoc-Anpassungen zu retten. Das verwandelt eine hypothesengesteuerte Korrektur in Raten.
Wenn die Ausführungsumgebung einen sauberen Rollback unterstützt (z. B. git checkout, git stash oder ein externer Rahmen, der den Patch-Zustand verwaltet), setzen Sie den fehlgeschlagenen Patch zurück, bevor Sie die Ausweichhypothese versuchen. Wenn ein Rollback nicht unterstützt wird, überprüfen und machen Sie die fehlgeschlagenen Änderungen explizit rückgängig, bevor Sie fortfahren — legen Sie keinen neuen Patch auf einen defekten.
Wählen Sie die nächste Hypothese aus der Hypothesennotiz aus (diejenige mit der nächstbesten Kombination von Beweisen und Risiko).
Dokumentieren Sie in der Patch-Entscheidungsnotiz: welche Hypothese fehlgeschlagen ist, warum (welcher Test brach), und welche Hypothese jetzt versucht wird.
Kehren Sie zu Schritt 2 mit der Ausweichhypothese zurück.

Wenn alle Hypothesen erschöpft sind und kein Patch die Tests besteht, melden Sie, dass der Hypothesensatz unzureichend ist — die Ursache wird möglicherweise von keiner hypothese erklärten Erklärung erfasst.

Ausgabe: Patch-Entscheidungsnotiz

Am Ende des Workflows (ob der Patch erfolgreich war oder fehlschlug), erstellen Sie eine Patch-Entscheidungsnotiz mit dieser genauen Struktur:

patch_decision_note:
  selected_hypothesis: <which hypothesis was patched>
  patch_scope: <one-sentence summary of what the patch changes>
  modified_files:
    - <file path>: <reason this file had to change>
    - <file path>: <reason this file had to change>
  side_effects_signals:
    ready_valid: <findings or "no issues found">
    reset_flush_replay: <findings or "no issues found">
    fsm_transitions: <findings or "no issues found">
    stale_state: <findings or "no issues found">
    pipeline_ordering: <findings or "no issues found">
  artifact_links_checked:
    config_files: <status or "not applicable">
    generated_files: <status or "not applicable">
    register_descriptions: <status or "not applicable">
    generator_scripts: <status or "not applicable">
  test_outcome: <all passed | some failed from patch>
  tests_failed: <list of tests that failed, if any>
  test_failures_caused_by_patch: <true | false>
  remaining_exhausted_hypotheses: <list of hypotheses tried and failed>
  overall_result: <patch applied successfully | patch not applied after all hypotheses>

Vermeidung von Modell-Zirkularität

Beachten Sie diese drei Prinzipien, um zu verhindern, dass das Modell in Endlosschleifen gerät:

Keine lokale Verifikation des Patches — Führen Sie kein Formales Verifizieren, keine Modellprüfung und keine symbolische Simulation des Patches durch. Führen Sie nur die Testsuite aus. In dieser Phase mit anderen Verifikationstools zu interagieren, erzeugt einen unendlichen Verifikationsregress.
Beginne nicht zu analysieren, warum der Test fehlschlägt — Wenn ein Test fehlschlägt, analysieren Sie nicht die Wellenform oder das Protokoll, um einen neuen Fehlerort zu finden. Das ist Aufgabe des Skills zur Fehlerlokalisierung. Wechseln Sie einfach zur nächsten Hypothese.
Erfinde keine neuen Hypothesen — Wenn alle Hypothesen aus der ursprünglichen Notiz ausgeschöpft sind, stoppen Sie. Generieren Sie keine neuen Hypothesen aus dem Fehlerprotokoll. Das betritt den Bereich der Fehlerlokalisierung und erzeugt eine endlose Schleife von Patch und Fehler bei jeder Ausführung.

Zeitüberschreitungsschutz

Die Verarbeitung jedes Schritts sollte in einer angemessenen Anzahl von Token erfolgen. Wenn ein bestimmter Schritt (wie die Artefakt-Verknüpfungsprüfung) zu lange dauert, geben Sie Teilergebnisse aus und fahren Sie fort, anstatt zu versuchen, den Schritt in einem einzigen, überlangen Aufruf abzuschließen.

AgainstWar/HDL-Reparatur-Skills

Was ist HDL-Reparatur-Skills?

In Ihrer bevorzugten KI fragen

Dokumentation