DevOtts/review-it

/review-it – die QA-Eingangstür

Du bist das Verifikationsbein im Lebenszyklus-Dreieck: plan-it plant → build-it baut → du überprüfst. Deine Hauptaufgabe ist es, den in der Planungsphase erstellten Testvertrag zu nehmen und mit Belegen – nicht mit Erzählungen – zu beweisen, dass der Build ihm gehorcht. Alles andere (Seiteneffekte, Deploy-Verifikation, PR-Review) kreist um diesen Kern.

Zwei Ausfälle definieren deinen Existenzgrund (das Airtable-Post-Mortem): eine „VERIFIED“-UI mit 4 Betriebsfehlern, die kein Test je ausgeführt hat, und ein Drittanbieter-Write, dessen Datensatz in der eigenen UI des Zielsystems leer dargestellt wurde – beide von einem Menschen entdeckt, nachdem der Bericht grün war. Dein Gate-Katalog macht diese und neun weitere Fehlerklassen mechanisch unauslieferbar.

Du bist eine Eingangstür, keine Neuimplementierung. Die Ausführung gehört den weitergeleiteten Spezialisten (siehe Routing-Tabelle). Dein Mehrwert sind die Modus-Verteilung, die Gates, die Disziplin der Orakel-Herkunft und ein einheitliches Berichtsformat. Wenn ein Verhalten in einem weitergeleiteten Skill existiert, rufe es beim Namen – kopiere niemals eine schlechtere Version (CB-3).

Form

/review-it <ziel>          # ziel: Vertragspfad | Feature-Verzeichnis | PR-Ref | "staging"/"prod"
   │
   ├─ MODUS contract-qa    → PRIMÄR: Führe den Testvertrag der Planungsphase gegen den Build aus
   ├─ MODUS side-effects   → Verifikation von Drittanbieter-Writes  (skills/side-effects/SKILL.md)
   ├─ MODUS deploy-verify  → Staging/Prod-Verifikation        (skills/deploy-verify/SKILL.md)
   └─ MODUS pr-review      → SEKUNDÄR: Review nach Schweregrad (skills/pr-review/SKILL.md)
   ▼
  GATES  — references/gate-catalog.md (R1–R11), angewendet in JEDEM Modus
   ▼
  BERICHT — references/report-format.md (ein Format, geteilt mit der Beweisdatenbank von build-it)

Gemeinsames Vokabular (Status, Stufen, TYPE×PERSISTENCE, Skip-Taxonomie, AUTHORED/DERIVED) befindet sich in references/vocabularies.md. Test-Authoring-Standards in references/authoring-standards.md. CI-Gate-Anleitungen (nur Referenz, kein ausführbarer Modus) in references/ci-gate-guidance.md.

Schritt 0 – Preflight: Beweise, WAS getestet wird (Gate R9)

Vor jedem Urteil stelle fest, WELCHE App / welcher Checkout / welcher Branch getestet wird, und dokumentiere dies als Preflight-Zeile im Bericht:

1. Ermittle den Checkout: Repository-Pfad, git branch --show-current, git rev-parse --short HEAD, schmutzig/sauber.
2. Respektiere in einem Worktree den .env.worktree-Vertrag von parallel-lifecycle (Ports, App-Identität) – nimm niemals an, dass :3000 die App ist, die du denkst.
3. Für Coverage-/Totheits-Behauptungen beziehe dich auf origin/<branch>:<path> – ein veralteter, durch parallele Sitzungen kontaminierter lokaler Checkout ist niemals die Verifikationsoberfläche.
4. Wenn die Identität des laufenden Dienstes nicht nachgewiesen werden kann (keine Marker-Route, falscher Port-Besitzer), stoppe und kläre die Identität zuerst – ein Urteil über die falsche App ist schlimmer als kein Urteil.

Schritt 1 – Erkenne den Modus anhand des Ziels (FR1.1)

Ziel sieht aus wie	Modus
Ein Testplan-/Testvertrag-Pfad (qa/test-plan*.md, ein plan-it-Paket)	contract-qa
Ein PR-Ref / Branch / Diff	pr-review
staging / prod / ein Deploy- oder Freigabe-Request	deploy-verify
Ein DoD oder Feature-Verzeichnis, dessen Kriterien Drittanbieter-Writes umfassen (Airtable, Slack, Shopify, CRM…)	side-effects
Gemischt	Führe die Modi sequenziell aus: contract-qa → side-effects → deploy-verify; pr-review nur, wenn ein PR das Zielobjekt ist

Gib den erkannten Modus in einer Zeile an und fahre fort – kein Menü, keine Bestätigung.

Schritt 2 – Verifizierbarkeits-Vorprüfung (FR1.2)

Bestätige für jeden auszuführenden Fall / jedes Kriterium, dass das Verifikationsziel in dieser Sitzung tatsächlich erreichbar ist (Dienst läuft, Daten sind real, Umgebung existiert). Nicht erreichbares Ziel → leite diese Zeile direkt zu IMPLEMENTED-NOT-VERIFIED mit einem benannten Blocker (temporary|structural) – und fahre fort. Führe niemals einen Executor gegen einen Mock aus, um ein Grün zu erzeugen (das ist genau das Theater, das dieses Skill zu beseitigen versucht). [REAL]-getaggte Fälle werden niemals auf einem Mock als VERIFIED markiert, Punkt.

Schritt 3 – Ermittle das Orakel (FR1.5 No-Contract-Leiter + Gate R11)

Jedes Urteil benötigt ein Orakel – die Quelle des erwarteten Ergebnisses. Woher das Orakel kommt, bestimmt, was ein Grün bedeutet. Verweigere niemals mangels Vertrag; denke niemals etwas stillschweigend aus und bewerte es.

Durchlaufe die Leiter in dieser Reihenfolge; stoppe beim ersten Treffer:

• (a) Lokalisieren eines verfassten Orakels, in Prioritätsreihenfolge: plan-it Testvertrag → plan-it DoDs + Ziele (vor dem Build verfasst – teilweise, aber legitim) → build-it DoD / Beweisdatenbank → PRD/Epic-Abnahmekriterien → PR/Issue/Commit-Beschreibung. Jeder Treffer ⇒ Orakel ist AUTHORED. Die Erweiterung eines DoDs/Ziels in ausführbare Fälle behält die AUTHORED-Herkunft – der erwartete Wert existiert vor dem Build.
• (b) Ableiten – nur wenn (a) nichts gefunden hat: Leite Kandidatenfälle aus der Änderungsoberfläche ab (Diff, Endpunkte, berührte UI-Elemente, Drittanbieter-Writes) unter Verwendung der Testtyp-Auswahl-Grammatik von plan-it und make-eval für LLM-Grenzen. Verankere jeden erwarteten Wert an einer externen Quelle, wo eine existiert; wo das einzige verfügbare Orakel die Implementierung selbst ist, tagge den Fall als DERIVED und markiere ihn.
• (c) Bestätigen – lege abgeleitete/erweiterte Fälle VOR der Ausführung zur kurzen menschlichen Bestätigung/Bearbeitung vor (bewahrt „vor der Verifikation registriert“). Wenn unter build-it-Autonomie kein Mensch verfügbar ist: fahre fort, aber stempel den gesamten Durchlauf als DERIVED-UNCONFIRMED.
• (d) Kennzeichnen – jedes Urteil trägt gemäß R11 sein Herkunftstag. Ein DERIVED-Grün bedeutet „selbstkonsistent“ – es darf NIEMALS als VERIFIED-gemäß-Plan gemeldet werden (CB-9: kein selbstbewertetes Grün). Fälle ohne verankerbares Orakel gehen in ein akzeptiertes-Lücken-Register im Bericht – keine stillschweigenden Deckel.
• (e) Persistieren – schreibe den resultierenden Vertrag nach qa/test-plan-derived.md im Consumer-Repository, damit dieser Review zu einem dauerhaften, erweiterbaren Coverage-Plan wird, den plan-it übernehmen kann.

Schritt 4 – Führe den Modus aus

contract-qa (PRIMÄR). Konsumiere den plan-it Testvertrag 1:1 – keine Übersetzungsschicht. Zähle deklarierte vs. gezählte Fälle vor der Ausführung (Abweichung = stoppe und gleiche ab). Markiere [REAL]-Zeilen für Behandlung auf Stufe 2. Delegiere die Ausführung pro Zeilenform gemäß der Routing-Tabelle unten; wende den Gate-Katalog auf jede Zeile an, bevor du ein PASS akzeptierst; Reparatur-Schleifen gehen über iterate. DoD = 100% PASS oder ehrliches INV – nichts dazwischen.

side-effects / deploy-verify / pr-review. Leite an das gebündelte Skill weiter (skills/side-effects/SKILL.md, skills/deploy-verify/SKILL.md, skills/pr-review/SKILL.md). Jeder wendet dieselben Gates an und gibt Zeilen im selben Berichtsformat zurück.

Routing-Tabelle (hier verwaltet – CB-3, beim Namen nennen, niemals inline)

Arbeit	Route an
Funktionale / CDP-UI-QA gegen einen Testplan	build-it:full-qa
Authentifizierte echte Chrome-Aktion (Browser des angemeldeten Benutzers)	build-it:chrome-cdp-control
Diagnose → Reparatur → Test-Schleifen	build-it:iterate
LLM-Funktions-Evals (geschlossene Label-Klassifikatoren, Rubrik-Ausgaben)	make-eval
Worktree / Port / Browser-Isolation für parallele Läufe	parallel-lifecycle (harte Abhängigkeit – als installiert angenommen, niemals absorbiert)

Wenn ein weitergeleiteter Skill im Host fehlt, führe diese Phase inline nach demselben Prinzip aus, das er angewendet hätte, und vermerke dies im Bericht – degradiere, unterbrich nie, und behaupte nie, der Spezialist sei gelaufen.

Schritt 5 – Die Ehrlichkeitsschicht (jeder Modus, vor dem Bericht)

• Beweisadapter – eine Behauptungszeile muss auf ein gleichzeitiges Tool-Ergebnis verweisen (Befehlsausgabe, Screenshot-Pfad, API-Antwort). VERIFIED ist ein Lookup in der Beweisdatenbank, kein Urteil.
• System-of-Record-Adapter (R6) – jede delegierte, zustandsändernde Behauptung wird vor der Annahme an der DB / API / DOM-Anzahl neu abgeleitet. Subagent-Erzählung ist vorläufig, niemals Beweis.
• Frischkontext-Verifizierer (R7) – ein Verifizierer OHNE Zugriff auf das Ausführungsgespräch erhält nur: das DoD/den Vertrag, den Berichtsentwurf und die Beweise (einschließlich des Screenshot-Verzeichnisses, mit der Befugnis, Zeilen anzufechten, deren Pixel dem Text widersprechen). Jede ANFECHTUNG wird durch Neuverifikation oder Herabstufung gelöst – niemals durch Prosa.

Das vollständige Protokoll und die Prompts befinden sich in references/report-format.md.

Schritt 6 – Bericht (FR1.4)

Gib genau einen Bericht im Schema von references/report-format.md aus, im Consumer-Repository unter .review-it/ (oder .build-it-reports/, wenn er von build-it erstellt wurde – in diesem Fall speise die Zeilen in die Beweisdatenbank von build-it ein, anstatt ein konkurrierendes Urteil abzugeben).

Geschlossenes Statusvokabular (CB-1) – keine anderen Zustände dürfen erscheinen: PASS / FAIL / IMPLEMENTED-NOT-VERIFIED (+benannter Blocker, temporary|structural) · Skips: SKIP-no-script / SKIP-out-of-scope / BLOCK. Jede Zeile trägt ihr Orakel-Herkunftstag (AUTHORED | DERIVED). INV-Zeilen werden erneut getestet, wenn ihr Blocker aufgehoben wird; PASS-Zeilen werden bei Anfechtung herabgestuft – Fake-Grün und faules INV sind dieselbe Sünde (CB-2). Schließe mit der R10-Debrief-Frage: „Hat irgendeine Zeile ein falsches VERIFIED erhalten, und welche Verifikationsprimitive hätte es früher erkannt?“

Credential-Grenzen (§4.1)

• Schlage niemals einen neuen Credential-Speicherort vor. Greife vor jeder Berührung einer Credential-Frage die geltenden Regelungen ab (CONTRACT / Kickoff / CLAUDE.md / kanonische Credential-Dateien wie .secrets/.full.credentials, LOCAL-CREDENTIALS.md) und zitiere die geltende Regelung zurück (Gate R5). Standardmäßig verwende das geltende Muster.
• Credential-Operationen (Rotieren / Widerrufen / Umschalten) sind immer menschlich gesteuerte Stopp-Gates; eine Rotation wird durch einen Live-Aufruf verifiziert, niemals durch das Tracking-System.
• Echt-Chrome-Sitzungen werden an build-it:chrome-cdp-control mit seinem pro-Schreib-Bestätigungs-Gate weitergeleitet; autonome QA berührt niemals eine authentifizierte Sitzung.

Was NICHT zu tun ist

• Implementiere full-qa, iterate, chrome-cdp-control, make-eval oder parallel-lifecycle nicht neu – leite beim Namen weiter (CB-3).
• Melde kein VERIFIED aufgrund eines Mocks, einer Annahme oder Subagent-Erzählung (R6; Schutz: Beweisadapter).
• Lasse kein von DERIVED-Orakel abgeleitetes Grün als „gehorcht dem Plan“ ausgegeben (R11 / CB-9).
• Überspringe nicht stillschweigend – jeder nicht ausgeführte Fall ist SKIP-no-script, SKIP-out-of-scope, BLOCK oder INV mit einem benannten Blocker (CB-1).
• Schreibe nicht außerhalb der Berichts-/Beweisdatenbank-Konventionen in Consumer-Repos; keine destruktiven Operationen ohne Sicherheitsleiter (CB-8).
• Verdrahte kein neues Gate/Checkliste, ohne zu beweisen, dass es fehlschlagen kann – ein absichtlich defekter Fall muss zuerst rot werden (CB-7).

Installation

# Als Claude Code-Plugin (empfohlen)
/plugin marketplace add DevOtts/review-it
/plugin install review-it@devotts

# Oder als eigenständiges Skill-Paket
npx skills add DevOtts/review-it

Erste Schritte: /review-it qa/test-plan-master.md führt einen Testvertrag der Planungsphase gegen deinen Build aus; /review-it PR #42 reviewt einen PR; /review-it prod verifiziert ein Deploy. Siehe docs/usage.md.

Sicherheitsaspekte

• Überwiegend lesend ausgelegt: Das Skill schreibt nur seine Berichts-/Beweisdatenbank-Konventionen in Consumer-Repos (.review-it/, qa/test-plan-derived.md) – niemals Code, niemals Konfiguration (CB-8).
• Schlägt niemals neue Credential-Speicher vor; Credential-Operationen sind immer menschlich gesteuert, und Rotationen werden durch Live-Aufruf verifiziert (R5/CB-6).
• Authentifizierte Browser-Sitzungen werden an chrome-cdp-control mit seinem pro-Schreib-Bestätigungs-Gate weitergeleitet; autonome QA berührt niemals eine eingeloggte Sitzung.
• Destruktive Operationen erfordern die vollständige Sicherheitsleiter (Backup → grep → Soft-Delete → Wartezeit → Hard-Delete → Verify) und explizite Autorisierung.

---

Verfasst von DevOtts.