Castle-Solutions/landing

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

• Standards: Entspricht der Code den dokumentierten Codierungsstandards des Repos?
• Spezifikation: Setzt der Code die ursprüngliche Anforderung / Spezifikation getreu um?

Beide Achsen laufen als parallele Sub-Agenten, damit sie sich gegenseitig nicht in die Quere kommen. Anschließend fasst dieses Skill ihre Ergebnisse zusammen.

Das Issue-Tracker 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 festgelegten Punkt festlegen

Was auch immer der Benutzer als festgelegten Punkt genannt hat (eine Commit-SHA, ein Branchname, ein Tag, main, HEAD~5 usw.). Wenn er keinen angegeben hat, fragen Sie danach.

Halten Sie den Diff-Befehl einmal fest: git diff <festgelegter-punkt>...HEAD (Drei-Punkte, damit der Vergleich gegen die Merge-Base erfolgt). Notieren Sie auch die Liste der Commits via git log <festgelegter-punkt>..HEAD --oneline.

Überprüfen Sie vor dem Fortfahren, ob der festgelegte Punkt aufgelöst werden kann (git rev-parse <festgelegter-punkt>) und der Diff nicht leer ist. Ein ungültiger Ref oder ein leerer Diff sollte hier fehlschlagen, nicht innerhalb zweier paralleler Sub-Agenten.

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, dass es keine gibt, überspringt der Spezifikation-Sub-Agent und meldet „keine Spezifikation verfügbar".

3. Die Quellen für Standards identifizieren

Durchsuchen Sie das Repo nach jeder Datei, die dokumentiert, wie Code geschrieben werden sollte. Wenn CODING_STANDARDS.md oder CONTRIBUTING.md existiert, muss es auf der Liste stehen.

Zusätzlich zu dem, was das Repo dokumentiert, enthält die Achse Standards immer die folgende Geruchs-Baseline: eine feste Menge von Fowler-Code-Gerüchen (Refactoring, Kap. 3), die selbst dann gilt, wenn ein Repo nichts dokumentiert. Zwei Regeln binden sie:

• Das Repo überschreibt. Ein dokumentierter Repo-Standard hat immer Vorrang; wenn er etwas befürwortet, das die Baseline beanstanden würde, unterdrücken Sie den Geruch.
• Immer eine Beurteilung. Jeder Geruch ist eine gekennzeichnete Heuristik („möglicher Feature Envy"), nie ein harter Verstoß. Wie bei jedem Standard hier: überspringen Sie alles, was bereits von Werkzeugen durchgesetzt wird.

Jeder Geruch beschreibt was er ist → wie man ihn behebt; 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 Logik erscheint in mehr als einem Hunk oder einer Datei in der Änderung. → Die gemeinsame Struktur extrahieren, von beiden Stellen aufrufen.
• Feature Envy: Eine Methode, die mehr auf die Daten eines anderen Objekts zugreift als auf ihre eigenen. → Die Methode auf das Objekt verschieben, um dessen Daten sie sich beneidet.
• Datenklumpen: Dieselben wenigen Felder oder Parameter reisen immer zusammen (ein Typ, der geboren werden will). → Sie zu einem Typ bündeln, diesen übergeben.
• Primitiv-Obsession: Ein primitiver Typ oder String steht für ein Fachkonzept, das einen eigenen Typ verdient. → Dem Konzept einen eigenen kleinen Typ geben.
• Wiederholte Switches: Derselbe switch/if-Block über denselben Typ taucht wiederholt in der Änderung auf. → Durch Polymorphie ersetzen oder eine Map, die beide Stellen gemeinsam nutzen.
• Schrotschuss-Operation: Eine logische Änderung erzwingt verstreute Änderungen über viele Dateien im Diff. → Die Änderungen in einem Modul zusammenfassen.
• Divergente Ä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: Abstraktionen, Parameter oder Hooks, die für Bedürfnisse hinzugefügt wurden, die die Spezifikation nicht hat. → Löschen; zurück inlinen, bis ein tatsächlicher Bedarf auftaucht.
• Nachrichtenketten: Lange a.b().c().d()-Navigation, auf die der Aufrufer nicht angewiesen sein sollte. → Den Durchlauf hinter einer Methode auf dem ersten Objekt verstecken.
• Mittelsperson: Eine Klasse oder Funktion, die meistens nur weiterdelegiert. → Sie entfernen, das eigentliche Ziel direkt aufrufen.
• Verweigertes Vermächtnis: Eine Unterklasse oder Implementierung, die das meiste, was sie erbt, ignoriert oder überschreibt. → Die Vererbung aufgeben, Komposition verwenden.

4. Beide Sub-Agenten parallel starten

Geben Sie beide Sub-Agent-Aufrufe gleichzeitig im Vordergrund aus und fassen Sie die zurückgegebenen Berichte zusammen.

Prompt für den Standards-Sub-Agent sollte enthalten:

• Den vollständigen Diff-Befehl und die Commit-Liste.
• Die Liste der Quellendateien für Standards, die Sie in Schritt 3 gefunden haben, plus die Geruchs-Baseline aus Schritt 3, vollständig eingefügt (der Sub-Agent hat sonst keinen Zugriff darauf).
• Die Anweisung: „Berichte pro relevanter Datei/Hunk: (a) jede Stelle, an der der Diff einen dokumentierten Standard verletzt: zitiere den Standard (Datei + Regel); und (b) jeden Geruch aus der Baseline, den du siehst: benenne ihn und zitiere den Hunk. Unterscheide harte Verstöße von Beurteilungen: Verstöße gegen dokumentierte Standards können hart sein, aber Baseline-Gerüche sind immer Beurteilungen, und ein dokumentierter Repo-Standard überschreibt die Baseline. Überspringe alles, was Werkzeuge durchsetzen. Unter 400 Wörtern."

Prompt für den Spezifikation-Sub-Agent sollte enthalten:

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

Wenn die Spezifikation fehlt, überspringe den Spezifikation-Sub-Agent und notiere dies im Abschlussbericht.

5. Zusammenführen

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

Beende mit einer einzeiligen Zusammenfassung: Gesamtanzahl der Befunde pro Achse und das schwerwiegendste Problem innerhalb jeder Achse (falls vorhanden). Wähle keinen einzelnen Gewinner über die Achsen hinweg: das ist die Neubewertung, die durch die Trennung verhindert werden soll.

Warum zwei Achsen

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

• Code, der jeden Standard einhält, 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.