pedro-oscar/shorts-ai

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 originalgetreu um?

Beide Achsen laufen als parallele Sub-Agenten, damit sie sich nicht gegenseitig in ihrem Kontext stören. Dann fasst dieses Skill ihre Ergebnisse zusammen.

Der Issue-Tracker sollte dir bereits mitgeteilt worden sein. Wenn nicht, sage dem Benutzer, er solle /setup-matt-pocock-skills ausführen.

Ablauf

1. Festen Punkt bestimmen

Was auch immer der Benutzer als festen Punkt angegeben hat (eine Commit-SHA, ein Branchname, ein Tag, main, HEAD~5, etc.). Falls keiner angegeben wurde, frage danach.

Halte den Diff-Befehl einmal fest: git diff <fester-punkt>...HEAD (Drei-Punkt, damit der Vergleich gegen den Merge-Base erfolgt). Notiere auch die Liste der Commits via git log <fester-punkt>..HEAD --oneline.

Bevor du fortfährst, überprüfe, ob sich der feste Punkt auflösen lässt (git rev-parse <fester-punkt>) und der Diff nicht leer ist. Ein fehlerhafter Ref oder ein leerer Diff sollten hier fehlschlagen, nicht innerhalb der beiden parallelen Sub-Agenten.

2. Spezifikationsquelle identifizieren

Suche nach der ursprünglichen Spezifikation, in dieser Reihenfolge:

1. Issue-Referenzen in den Commit-Nachrichten (#123, Closes #45, GitLab !67, etc.), abgerufen über den Workflow im Tracker-Dokument.
2. Ein vom Benutzer als Argument übergebener Pfad.
3. Eine Spezifikationsdatei unter docs/, specs/ oder .scratch/, die dem Branchnamen oder Feature entspricht.
4. Wenn nichts gefunden wird, frage den Benutzer, wo die Spezifikation ist. Sagen sie, es gibt keine, überspringt der Spezifikations-Sub-Agent und meldet "Keine Spezifikation verfügbar".

3. Quellen für Standards identifizieren

Durchsuche das Repository nach jeder Datei, die dokumentiert, wie Code geschrieben werden soll. Wenn CODING_STANDARDS.md oder CONTRIBUTING.md existiert, muss es auf der Liste stehen.

Zusätzlich zu dem, was das Repository dokumentiert, trägt die Standards-Achse immer die folgende Code-Gerüche-Basislinie: einen festen Satz von Fowler-Code-Gerüchen (Refactoring, Kap. 3), der auch dann gilt, wenn ein Repository nichts dokumentiert. Zwei Regeln binden sie:

• Das Repository überschreibt. Ein dokumentierter Repo-Standard hat immer Vorrang; wo er etwas befürwortet, das die Basislinie beanstanden würde, unterdrücke den Geruch.
• Immer eine Ermessensentscheidung. Jeder Geruch ist eine beschriftete Heuristik ("mögliches Feature Envy"), niemals eine harte Verletzung. Wie bei jedem Standard hier, überspringe alles, was bereits durch Tooling erzwungen wird.

Jeder Geruch beschreibt was er ist → wie zu beheben; gleiche ihn mit dem Diff ab:

• Geheimnisvoller Name: Eine Funktion, Variable oder ein Typ, dessen Name nicht verrät, was sie tun oder enthalten. → umbenennen; wenn kein ehrlicher Name einfällt, ist das Design unklar.
• Duplizierter Code: Dasselbe Logikmuster erscheint in mehr als einem Hunk oder in mehr als einer Datei in der Änderung. → extrahiere die gemeinsame Form, rufe sie von beiden Stellen auf.
• Feature Envy: Eine Methode, die mehr in die Daten eines anderen Objekts greift als in ihre eigenen. → verschiebe die Methode zu den Daten, die sie begehrt.
• Datenklumpen: Dieselben wenigen Felder oder Parameter reisen ständig zusammen (ein Typ, der geboren werden möchte). → bündele sie in einem Typ, übergib diesen.
• Primitive Besessenheit: Ein primitiver Wert oder String steht für ein Domänenkonzept, das einen eigenen Typ verdient. → gib dem Konzept einen eigenen kleinen Typ.
• Wiederholte Switches: Derselbe switch/if-Kaskade auf demselben Typ wiederholt sich in der Änderung. → ersetze durch Polymorphie oder eine Map, die beide Stellen teilen.
• Schrotschuss-Chirurgie: Eine logische Änderung erzwingt verstreute Änderungen über viele Dateien im Diff. → sammle, was sich ändert, in einem Modul.
• Abweichende Änderung: Eine Datei oder ein Modul wird aus mehreren nicht zusammenhängenden Gründen bearbeitet. → trenne so, dass jedes Modul sich aus einem Grund ändert.
• Spekulative Allgemeinheit: Abstraktion, Parameter oder Hooks, die für Bedürfnisse hinzugefügt wurden, die die Spezifikation nicht hat. → lösche sie; inline zurück, bis ein echtes Bedürfnis auftaucht.
• Nachrichtenketten: Lange a.b().c().d()-Navigation, von der der Aufrufer nicht abhängen sollte. → verstecke den Durchlauf hinter einer Methode auf dem ersten Objekt.
• Mittelsmann: Eine Klasse oder Funktion, die meist nur weiterdelegiert. → schneide sie heraus, rufe das eigentliche Ziel direkt auf.
• Verweigerte Hinterlassenschaft: Eine Unterklasse oder Implementierer, die das meiste, was sie erbt, ignoriert oder überschreibt. → wirf die Vererbung ab, verwende Komposition.

4. Beide Sub-Agenten parallel starten

Starte beide Sub-Agenten-Aufrufe gleichzeitig im Vordergrund und fasse die von ihnen zurückgegebenen Berichte zusammen.

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

• Den vollständigen Diff-Befehl und die Commit-Liste.
• Die Liste der von dir in Schritt 3 gefundenen Quellen-Dateien, plus die Code-Gerüche-Basislinie aus Schritt 3 vollständig eingefügt (der Sub-Agent hat keinen anderen Zugriff darauf).
• Die Anweisung: "Berichte pro Datei/Hunk, wo relevant: (a) jede Stelle, an der der Diff einen dokumentierten Standard verletzt: zitiere den Standard (Datei + Regel); und (b) jeden von dir bemerkten Basislinien-Geruch: nenne ihn und zitiere den Hunk. Unterscheide harte Verletzungen von Ermessensentscheidungen: Verstöße gegen dokumentierte Standards können hart sein, aber Basislinien-Gerüche sind immer Ermessensentscheidungen, und ein dokumentierter Repo-Standard überschreibt die Basislinie. Überspringe alles, was durch Tooling erzwungen wird. Unter 400 Wörtern."

Prompt für den Spezifikations-Sub-Agenten sollte enthalten:

• Den Diff-Befehl und die Commit-Liste.
• Den Pfad oder die abgerufenen Inhalte der Spezifikation.
• Die Anweisung: "Berichte: (a) Anforderungen, die von der Spezifikation gefordert, aber fehlend oder unvollständig sind; (b) Verhalten im Diff, das nicht gefordert war (Scope Creep); (c) Anforderungen, die implementiert aussehen, aber bei denen die Implementierung falsch aussieht. Zitiere für jede Feststellung die Zeile der Spezifikation. Unter 400 Wörtern."

Falls die Spezifikation fehlt, überspringe den Spezifikations-Sub-Agenten und vermerke dies im Abschlussbericht.

5. Zusammenführen

Präsentiere die beiden Berichte unter den Überschriften ## Standards und ## Spezifikation, 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).

Schließe mit einer einzeiligen Zusammenfassung ab: Gesamtzahl der Feststellungen pro Achse und die schwerwiegendste Feststellung innerhalb jeder Achse (falls vorhanden). Wähle keinen einzelnen Sieger über die Achsen hinweg aus: das ist die Neubewertung, die die Trennung verhindern soll.

Warum zwei Achsen

Eine Änderung kann die eine Achse bestehen und an der anderen scheitern:

• Code, der jeden Standard befolgt, aber die falsche Sache implementiert → Standards bestanden, Spezifikation nicht bestanden.
• Code, der genau das tut, was das Issue verlangt, aber die Projektkonventionen bricht → Spezifikation bestanden, Standards nicht bestanden.

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