Razsk/VideoStudio

Zweiachsige Überprüfung des Diffs zwischen HEAD und einem vom Benutzer angegebenen festen Punkt:

• Standards: Entspricht der Code den dokumentierten Codierungsstandards dieses Repos?
• Spezifikation: Setzt der Code das ursprüngliche Issue/die Spezifikation korrekt um?

Beide Achsen werden als parallele Unteragenten ausgeführt, damit sie sich gegenseitig nicht den Kontext stören. Danach fasst dieses Skill ihre Ergebnisse zusammen.

Das Issue-Tracking sollte Ihnen zur Verfügung gestellt worden sein. Falls nicht, sagen Sie dem Benutzer, er solle /setup-matt-pocock-skills ausführen.

Ablauf

1. Den festen Punkt festlegen

Was auch immer der Benutzer als festen Punkt angegeben hat (ein Commit-Hash, Branchname, Tag, main, HEAD~5 usw.). Falls keiner angegeben wurde, fragen Sie danach.

Erfassen Sie den Diff-Befehl einmal: git diff <fester-Punkt>...HEAD (mit drei Punkten, sodass der Vergleich gegen die Merge-Base erfolgt). Notieren Sie auch die Liste der Commits über git log <fester-Punkt>..HEAD --oneline.

Bevor Sie fortfahren, bestätigen Sie, dass der feste Punkt aufgelöst werden kann (git rev-parse <fester-Punkt>) und der Diff nicht leer ist. Ein ungültiger Ref oder ein leerer Diff sollte hier fehlschlagen, nicht innerhalb der zwei parallelen Unteragenten.

2. Die Spezifikationsquelle identifizieren

Suchen Sie nach der ursprünglichen Spezifikation, in dieser Reihenfolge:

1. Issue-Referenzen in den Commit-Nachrichten (#123, Closes #45, GitLab !67 usw.), abgerufen über den Workflow im Tracker-Dokument.
2. Ein Pfad, den der Benutzer als Argument übergeben hat.
3. Eine Spezifikationsdatei unter docs/, specs/ oder .scratch/, die dem Branchnamen oder Feature entspricht.
4. Wenn nichts gefunden wird, fragen Sie den Benutzer, wo die Spezifikation ist. Wenn der Benutzer sagt, es gibt keine, wird der Spec-Unteragent überspringen und "keine Spezifikation verfügbar" melden.

3. Die Standards-Quellen identifizieren

Durchsuchen Sie das Repo nach allen Dateien, die dokumentieren, wie Code geschrieben werden soll. Wenn CODING_STANDARDS.md oder CONTRIBUTING.md existieren, müssen sie auf der Liste stehen.

Zusätzlich zu dem, was das Repo dokumentiert, führt die Standards-Achse immer die folgende Geruchs-Baseline mit: einen festen Satz von Fowler-Code-Smells (Refactoring, Kap. 3), der auch dann gilt, wenn ein Repo nichts dokumentiert. Zwei Regeln binden sie:

• Das Repo überschreibt. Ein dokumentierter Repo-Standard hat immer Vorrang; wo er etwas befürwortet, das die Baseline kennzeichnen würde, wird der Geruch unterdrückt.
• Immer eine Ermessensentscheidung. Jeder Geruch ist eine beschriftete Heuristik ("möglicher Feature Neid"), niemals ein harter Verstoß. Wie bei jedem Standard hier: überspringen Sie alles, was Tooling bereits durchsetzt.

Jeder Geruch gibt an, was er ist → wie zu beheben; gleichen Sie ihn gegen den Diff ab:

• Mysteriöser Name: Eine Funktion, Variable oder ein Typ, dessen Name nicht verrät, was sie/er tut oder enthält. → umbenennen; wenn kein ehrlicher Name einfällt, ist das Design unklar.
• Duplizierter Code: Dieselbe Logikform taucht in mehr als einem Hunk oder einer Datei in der Änderung auf. → die gemeinsame Form extrahieren, von beiden Stellen aufrufen.
• Feature Neid: Eine Methode, die mehr in die Daten eines anderen Objekts greift als in ihre eigenen. → die Methode auf die Daten verschieben, die sie beneidet.
• Datenklumpen: Dieselben wenigen Felder oder Parameter reisen ständig zusammen (ein Typ, der geboren werden will). → sie in einen Typ bündeln, diesen übergeben.
• Primitiven-Besessenheit: Ein primitiver Typ oder String, der für ein Domänenkonzept steht, das einen eigenen Typ verdient. → dem Konzept einen eigenen kleinen Typ geben.
• Wiederholte Switchs: Dieselbe switch/if-Kaskade über denselben Typ tritt in der Änderung wiederholt auf. → durch Polymorphie ersetzen oder eine Map, die beide Stellen gemeinsam nutzen.
• Schrotflinten-Operation: Eine logische Änderung erzwingt verteilte Änderungen über viele Dateien im Diff. → zusammenführen, was sich ändert, in ein Modul.
• Abweichende Änderung: Eine Datei oder ein Modul wird aus mehreren, nicht zusammenhängenden Gründen bearbeitet. → aufteilen, sodass jedes Modul sich aus einem Grund ändert.
• Spekulative Allgemeinheit: Abstraktion, Parameter oder Hooks, die für Anforderungen hinzugefügt wurden, die die Spezifikation nicht hat. → löschen; inline zurückführen, bis ein echter Bedarf auftaucht.
• Nachrichtenketten: Lange a.b().c().d()-Navigation, von der der Aufrufer nicht abhängen sollte. → den Durchlauf hinter einer Methode auf dem ersten Objekt verstecken.
• Mittelsmann: Eine Klasse oder Funktion, die meist nur weiterdelegiert. → entfernen, das eigentliche Ziel direkt aufrufen.
• Verweigertes Erbe: Eine Unterklasse oder Implementierung, die den Großteil dessen, was sie erbt, ignoriert oder überschreibt. → die Vererbung aufgeben, Komposition verwenden.

4. Beide Unteragenten parallel starten

Starten Sie beide Unteragentenaufrufe gleichzeitig im Vordergrund und fassen Sie die Berichte zusammen, die sie zurückgeben.

Standards-Unteragentenaufforderung sollte enthalten:

• Den vollständigen Diff-Befehl und die Commit-Liste.
• Die Liste der in Schritt 3 gefundenen Standards-Quelldateien, plus die Geruchs-Baseline aus Schritt 3, vollständig eingefügt (der Unteragent hat sonst keinen Zugriff darauf).
• Die Anweisung: "Berichten Sie pro Datei/Hunk, wo relevant, (a) jede Stelle, an der der Diff einen dokumentierten Standard verletzt: zitieren Sie den Standard (Datei + die Regel); und (b) jeden Baseline-Geruch, den Sie entdecken: benennen Sie ihn und zitieren Sie den Hunk. Unterscheiden Sie harte Verstöße von Ermessensentscheidungen: Verstöße gegen dokumentierte Standards können hart sein, aber Baseline-Gerüche sind immer Ermessensentscheidungen, und ein dokumentierter Repo-Standard überschreibt die Baseline. Überspringen Sie alles, was Tooling bereits durchsetzt. Unter 400 Wörtern."

Spec-Unteragentenaufforderung sollte enthalten:

• Den Diff-Befehl und die Commit-Liste.
• Den Pfad oder den abgerufenen Inhalt der Spezifikation.
• Die Anweisung: "Berichten Sie: (a) Anforderungen, die die Spezifikation verlangt hat, die aber fehlen oder unvollständig sind; (b) Verhalten im Diff, das nicht angefragt wurde (Scope Creep); (c) Anforderungen, die implementiert aussehen, aber die Implementierung falsch aussieht. Zitieren Sie die Spezifikationszeile für jeden Befund. Unter 400 Wörtern."

Wenn die Spezifikation fehlt, überspringen Sie den Spec-Unteragenten und vermerken Sie dies im Abschlussbericht.

5. Zusammenführen

Präsentieren Sie die beiden Berichte unter den Überschriften ## Standards und ## Spec, wörtlich oder leicht bereinigt. Führen Sie die Befunde nicht zusammen oder ordnen Sie sie neu, da die beiden Achsen bewusst getrennt sind (siehe Warum zwei Achsen).

Schließen Sie mit einer einzeiligen Zusammenfassung ab: Gesamtbefunde pro Achse und der schwerwiegendste Befund innerhalb jeder Achse (falls vorhanden). Wählen Sie keinen einzelnen Gewinner über die Achsen hinweg: das ist die Neugewichtung, die die Trennung verhindern soll.

Warum zwei Achsen

Eine Änderung kann eine Achse bestehen und die andere nicht bestehen:

• Code, der jedem Standard folgt, aber das Falsche implementiert → Standards bestanden, Spezifikation nicht bestanden.
• Code, der genau das tut, was das Issue verlangt, aber die Konventionen des Projekts bricht → Spezifikation bestanden, Standards nicht bestanden.

Die getrennte Berichterstattung verhindert, dass eine Achse die andere überdeckt.