review-code

Code-Review-Skill

Überprüfe einen PR, indem du ALLE Fragen generierst und beantwortest, die sich aus den Review-Prinzipien ableiten. Erstelle ein finales Dokument mit spezifischen PR-Kommentaren und Verweisen auf die verwendeten Analyseartefakte.

Funktionsweise

Code-Review ist Befragung: generiere Fragen, beantworte alle, und decke auf, was unklar oder bedenklich ist.

Was dieses Skill produziert:

• Aus den Review-Prinzipien abgeleitete Fragen
• Antworten auf jede Frage (oder explizites „bedarf Autor“)
• Aus den Antworten gezogene Implikationen
• Aufgedeckte Bedenken, kategorisiert nach Typ

Was dieses Skill NICHT produziert:

• Schweregrade (kritisch/wesentlich/gering)
• Blockierend vs. nicht-blockierend Klassifizierungen
• Genehmigungsempfehlungen

Prozess: 0. Einrichtung – PR-Branch lokal auschecken

1. Erkundung – PR-Territorium kartieren, erste Fragen generieren (kann oberflächlich sein)
2. Fragen verfeinern – Wissenslücken füllen, echten Fragenkatalog generieren, nach Typ klassifizieren
3. Fragen beantworten – Jede Frage an den passenden Bearbeiter weiterleiten, Q&A-Dokument erstellen
4. Holistische Vorprüfung – Ansatz anhand der Q&A bewerten (parallel zu Schritt 5)
5. Pro-Commit-Review – Jeden Commit anhand der Q&A überprüfen (parallel) 5.5. Implikationen filtern – Binäre Entscheidung zur Offenlegung + Kategorisierung
6. Holistische Nachprüfung – Neu bewerten, Erfüllung der Anforderungen prüfen
7. Synthese – Zusammenführen zu Bedenken, geordnet nach Kategorie

Fragetypen und Bearbeiter:

• FAKT → fact-find-Skill (mit Quellenangaben)
• RECHERCHE → deep-research-Skill (weiterführende Dokumente)
• DESIGN → Designbewertung (Alternativen vorschlagen, an Prinzipien messen)
• KORREKTHEIT → Korrektheitsanalyse (Code nachvollziehen, Verhalten verifizieren)
• INTENTION → als „bedarf Autor“ markiert (kann nicht selbst beantwortet werden)

Wichtige Einsicht: Jede Frage erhält eine explizite, dokumentierte Antwort (oder explizites „bedarf Autor“). So entstehen überprüfbare Artefakte.

Eingabe

• PR-Referenz (URL, Nummer oder Branch)
• Optional: vom Nutzer genannte kritische Probleme oder Dokumentation

Einrichtung

Vor dem Start checkt der Orchestrator den PR aus:

# Im Ziel-Repository-Verzeichnis
gh pr checkout <PR-Nummer>

Voraussetzungen:

• Das Arbeitsverzeichnis muss das Repository mit dem PR sein
• Keine uncommitteten Änderungen (frühzeitig abbrechen bei „dirty“)
• GitHub-CLI authentifiziert

Nach dem Auschecken lesen alle Unteragenten den Code vom lokalen Dateisystem, anstatt gh CLI für Diffs zu verwenden.

Arbeitsbereich

Erstelle planning/<pr-slug>/ für alle Artefakte. Commite diese Artefakte nicht – sie sind Arbeitsdokumente, keine Liefergegenstände.

planning/<pr-slug>/
├── 00-scout.md           # Erste Gebietskarte
├── 01-questions.md       # Verfeinerter und klassifizierter Fragenkatalog
├── 02-answers.md         # Konsolidiertes Q&A-Dokument
├── answers/              # Einzelne Antwortartefakte
│   ├── fact-Q1.md
│   ├── design-Q2.md
│   └── ...
├── 03-commit-NN.md       # Pro-Commit-Reviews
├── 04-holistic-pre.md
├── filtered-implications.md  # Kategorisierte Implikationen zur Offenlegung
├── 05-holistic-post.md
└── REVIEW.md             # Endgültige Ausgabe

Unteragenten-Protokoll

Zu übergebende Dateien: PRINCIPLES.md, die Agenten-Anweisungsdatei, Artefakte aus vorherigen Phasen

Zu übergebende Daten: workspace-Pfad, phasenspezifische Daten

Antworten:

OUTPUT: <Dateiname>
STATUS: ok | problems
NOTES: <bei problems>

Vertraue STATUS: ok. Bei problems die Notizen lesen und entscheiden.

Repository-Zugriff

Der PR wird vor Beginn des Reviews lokal ausgecheckt. Unteragenten erhalten:

• repo_path: Pfad zum Repository mit ausgechecktem PR
• base_ref: Der Basis-Branch (z. B. main)
• head_ref: Der PR-Branch (ausgecheckt)

Unteragenten lesen Dateien direkt aus repo_path. Verwende git diff {base_ref}...HEAD für Diffs.

Phasen

0. Einrichtung

Checke den PR vor jeder Analyse lokal aus:

git pr checkout <PR-Nummer>

Erfasse base_ref aus den PR-Metadaten für Diff-Befehle.

1. Erkundung

Agent: agents/01-scout.md Dateien: PRINCIPLES.md, Agenten-Datei Daten: workspace, repo_path, base_ref, pr_number, Benutzerkontext Ausgabe: 00-scout.md

2. Fragen verfeinern

Agent: agents/02-refine-questions.md Dateien: PRINCIPLES.md, Agenten-Datei, 00-scout.md Daten: workspace, repo_path, base_ref, verknüpfte Issues/Dokumente Ausgabe: 01-questions.md

Diese Phase nutzt fact-find, um Wissenslücken zu füllen, und erstellt einen klassifizierten Fragenkatalog.

3. Fragen beantworten

Starte für jede Frage in 01-questions.md den passenden Antwort-Agenten:

Typ	Agent	Ausgabe
FAKT	agents/03-answer-fact.md	answers/fact-{id}.md
RECHERCHE	agents/04-answer-research.md	answers/research-{id}.md
DESIGN	agents/05-answer-design.md	answers/design-{id}.md
KORREKTHEIT	agents/06-answer-correctness.md	answers/correctness-{id}.md
INTENTION	(überspringen – als „bedarf Autor“ markieren)

Führe die Antwort-Agenten parallel aus, wenn möglich.

Nach Abschluss konsolidiere alles in 02-answers.md:

# Beantwortete Fragen

| ID | Typ | Frage | Antwortzusammenfassung | Detail |
|----|-----|-------|------------------------|--------|
| Q1 | FAKT | ... | ... | [answers/fact-Q1.md] |

## Bedarf Autor
| ID | Frage | Warum wir nicht antworten können |

4. Holistische Vorprüfung

Agent: agents/07-holistic-pre.md Dateien: PRINCIPLES.md, Agenten-Datei, 01-questions.md, 02-answers.md Daten: workspace, PR-Beschreibung, Commit-Nachrichten Ausgabe: 04-holistic-pre.md

Kann parallel zu Phase 5 ausgeführt werden.

5. Pro-Commit-Review

Agent: agents/08-commit-review.md (einer pro Commit, parallel) Dateien: PRINCIPLES.md, Agenten-Datei, 01-questions.md, 02-answers.md Daten: workspace, repo_path, base_ref, commit_sha, commit_message, commit_number, total_commits, all_commit_messages Ausgabe: 03-commit-NN.md

for each commit in PR:
    spawn commit_reviewer(
        commit_diff=commit.diff,
        commit_number=N,
        ...
    ) → 03-commit-{N}.md
# Ein Agent pro Commit – nicht bündeln

5.5. Implikationen filtern

Agent: agents/085-filter-implications.md Dateien: PRINCIPLES.md, Agenten-Datei, alle 03-commit-*.md Daten: workspace Ausgabe: filtered-implications.md

Der Agent parst Implikationen und Autorenfragen direkt aus den Commit-Review-Dateien.

Binäre Entscheidung zur Offenlegung (offenlegen oder nicht) plus Kategorisierung:

• correctness – Logikfehler, Bugs, fehlerhaftes Verhalten
• assumption – Nicht genannte Annahmen, die möglicherweise nicht zutreffen
• type-system – Typ-Sicherheitsbedenken, fehlende Constraints
• intent – Fragen zur Absicht des Autors, die Klärung benötigen

spawn implication_filter(workspace=workspace) → filtered-implications.md
# Agent extrahiert Implikationen aus 03-commit-*.md-Dateien

6. Holistische Nachprüfung

Agent: agents/09-holistic-post.md Dateien: PRINCIPLES.md, Agenten-Datei, 01-questions.md, 02-answers.md, 04-holistic-pre.md, alle 03-commit-*.md, filtered-implications.md Daten: workspace Ausgabe: 05-holistic-post.md

7. Synthese

Agent: agents/10-synthesize.md Dateien: PRINCIPLES.md, Agenten-Datei, alle Artefakte Daten: workspace Ausgabe: REVIEW.md

Ordne die aufgedeckten Bedenken nach Kategorie (correctness, assumption, type-system, intent), nicht nach Schweregrad.

8. Auslieferung

Präsentiere REVIEW.md dem Benutzer.

⚠️ NUR LOKAL: Dieses Skill erzeugt ausschließlich lokale Artefakte. Biete NICHT an, Kommentare auf GitHub zu posten oder mit GitHub zu interagieren, über das anfängliche gh pr checkout hinaus. Das Review-Ergebnis dient dem Benutzer zur manuellen Bearbeitung.

Token-Schonung

Du orchestrierst; Unteragenten analysieren. Vertraue den Status-Antworten.

Lese Zwischenartefakte NUR, wenn:

• STATUS: problems → Notizen lesen
• Der Benutzer eine Frage stellt
• Du einen Fehler behebst

Immer lesen: Status-Antworten, finales REVIEW.md.

Skill-Dateien

skills/review-code/
├── SKILL.md
├── PRINCIPLES.md
└── agents/
    ├── 01-scout.md
    ├── 02-refine-questions.md
    ├── 03-answer-fact.md
    ├── 04-answer-research.md
    ├── 05-answer-design.md
    ├── 06-answer-correctness.md
    ├── 07-holistic-pre.md
    ├── 08-commit-review.md
    ├── 085-filter-implications.md
    ├── 09-holistic-post.md
    └── 10-synthesize.md