BuilderIO/visual-recap

Visual Recap

/visual-recap erstellt einen visuellen Plan, der aus einem Diff aufgebaut ist, nicht auf einen hin. Es ist die Umkehrung der Vorwärtsplanung: Anstatt die Änderung zu beschreiben, die Sie gleich vornehmen werden, beschreiben Sie die Änderung, die gerade vorgenommen wurde, auf einer höheren Ebene als der zeilenweisen Überprüfung. Dasselbe Datenmodell dient beiden Richtungen — Schema-, API-, Datei- und Architekturänderungen werden zu denselben data-model, api-endpoint, file-tree und diagram Blöcken, die ein Vorwärtsplan verwenden würde, nur dass sie jetzt vorhandene Arbeiten zusammenfassen. Ein Reviewer scannt die Form der Änderung, bevor er seine Aufmerksamkeit auf die wörtlichen Zeilen verwendet.

Als Agent-Native Plan veröffentlichen — niemals Inline

Die Ausgabe ist IMMER ein veröffentlichter Agent-Native Plan, erstellt mit create-visual-recap auf dem Plan MCP Connector — NIEMALS Inline-Chat-Inhalt (kein Markdown-Text, keine ASCII-Skizze, keine Tabelle, kein umrahmter "Wireframe" oder eine Zusammenfassung vom Typ "hier ist das Recap"). Der gesamte Wert des Recaps liegt im gehosteten, interaktiven, annotierbaren Plan; eine Inline-Zusammenfassung ist kein minderwertiges Recap, sondern das, was ein Recap ersetzt. Wenn die plan (oder legacy agent-native-plans) Werkzeuge nicht sichtbar sind, entdecken Sie sie zuerst über die tool_search des Hosts; wenn sie immer noch fehlen, STOPPEN Sie und geben Sie dem Benutzer den client-spezifischen Wiederverbindungsschritt, anstatt ein Inline-Recap zu improvisieren. Lesen Sie vor dem Veröffentlichen oder wann immer ein Connector- oder Authentifizierungsfehler auftritt, references/connection.md in diesem Skill-Verzeichnis — es ist die einzige Quelle der Wahrheit für die Nie-Inline-Regel, die Connector-Erkennung und die Wiederverbindungsschritte pro Client. Der lokale Dateien-Datenschutzmodus (unten) ist die eine Ausnahme.

Lokaler Dateien-Datenschutzmodus — lesen Sie references/local-files.md

Wenn der Benutzer keine gehosteten Plan-Datenbankschreibvorgänge wünscht — keine DB-Schreibvorgänge, keine Plan MCP Veröffentlichung, vollständig lokale/offline/private Recaps oder AGENT_NATIVE_PLANS_MODE=local-files — rufen Sie kein gehostetes Plan-Tool auf, außer dem schema-only get-plan-blocks Katalog-Lookup. Lesen Sie den Diff mit den lokalen recap collect-diff / scan / build-prompt --local-files Helfern, erstellen Sie einen lokalen MDX-Ordner (setzen Sie kind: "recap" und localOnly: true) und zeigen Sie ihn mit plan local check, plan local serve --kind recap und plan local verify --kind recap an. Bevor Sie den lokalen Dateien-Modus verwenden, lesen Sie references/local-files.md in diesem Skill-Verzeichnis — es ist die einzige Quelle der Wahrheit für den vollständigen Vertrag.

Wann zu verwenden

Erstellen Sie ein Recap, wenn ein PR oder Commit groß ist, mehrere Dateien umfasst oder Schema-, API-Verträge oder Architektur betrifft, und ein Reviewer davon profitieren würde, die Änderung in strukturierten Blöcken abgebildet zu sehen, bevor er den rohen Diff liest. Eine GitHub Action kann automatisch eines aus einem PR-Diff generieren; ein Agent kann eines auf Anfrage generieren ("fasse diesen PR zusammen", "zeig mir, was dieser Branch geändert hat"). Überspringen Sie es für kleine, einzeldateiige oder offensichtliche Diffs — ein Recap ist ein Review-Overhead, und eine winzige Änderung reviewt sich schneller als einfacher Diff.

Das gesamte Arbeitseinheit zusammenfassen

Wenn /visual-recap in einem Chat-Thread aufgerufen wird, nachdem bereits gearbeitet wurde, ist der Standardumfang die gesamte aktuelle Arbeitseinheit/der gesamte Thread, nicht nur die letzte Benutzernachricht, Tool-Aktion oder Folgekorrektur. Sammeln Sie die dem Thread gehörenden Änderungen über das gesamte Gespräch: ursprüngliche Implementierungsarbeit, spätere Fehlerbehebungen, UI-Folgearbeiten, Tests, Changesets, Skill-/Anweisungsaktualisierungen, generierte Plan-/Quellartefakte und alle lokalen Import-/Verknüpfungskorrekturen, die erforderlich sind, um das Recap zu öffnen.

Verwenden Sie den aktuellen Diff plus Konversationskontext, um dem Thread gehörende Änderungen von nicht zusammenhängenden schmutzigen Arbeiten zu trennen, die vor dem Thread existierten. Schließen Sie nicht zusammenhängende vorherige Bearbeitungen aus. Wenn der Umfang wirklich mehrdeutig ist und nicht abgeleitet werden kann, geben Sie die Annahme an oder stellen Sie eine präzise Frage, bevor Sie veröffentlichen.

Wenn Sie ein vorhandenes Recap nach Feedback aktualisieren, überarbeiten Sie das Recap so, dass es immer noch den gesamten Thread/die gesamte Arbeitseinheit plus die neue Korrektur abdeckt. Ersetzen Sie kein breites Recap mit einem schmalen Recap, das nur das neueste Feedback betrifft, es sei denn, der Benutzer fordert ausdrücklich diesen engeren Umfang an.

Halten Sie den Recap-Text schlank

Fügen Sie dem generierten Plantext keine Boilerplate-Einleitung, keinen Haftungsausschluss, keine Herkunfts- oder Zusammenfassungstextblöcke hinzu. Erstellen Sie insbesondere keinen rich-text Block, nur um zu sagen, dass das Recap eine Hilfe ist, dass der Reviewer den Diff trotzdem überprüfen sollte, wie viele Dateien geändert wurden oder welcher Referenz-/Arbeitsbaum das Recap generiert hat. Der Planname, die Kurzbeschreibung und der file-tree (der die Änderungsstatistiken pro Datei enthält) tragen diesen Kontext bereits.

Fügen Sie nur dann Textblöcke hinzu, wenn sie dem Reviewer etwas Spezifisches über die Änderung mitteilen, das die strukturierten Blöcke nicht tun: das Ziel, ein echtes Kompatibilitätsrisiko, eine wichtige Entscheidung, die im Diff sichtbar ist, oder eine fundierte Review-Notiz.

Recaps müssen substanziell sein

Schlank ist nicht dasselbe wie dünn. Ein Recap ist nicht ein einzelnes Wireframe plus ein Satz — das unterfordert den Reviewer genauso, wie Boilerplate-Text ihn überfordert. Neben der visuellen/strukturellen Überschrift (Wireframes, data-model, api-endpoint, diagram) enthält ein substanzielles Recap auch die Implementierungsnachweise:

• Eine kurze Oberflächen-/Zustandsbestandsaufnahme vor dem Verfassen: Listen Sie die geänderten Routen, Komponenten, Popover/Dialoge, Rollen-/Zugriffsstatus, Leer-/Fehlerzustände und gemeinsamen Abstraktionen auf, die im Diff sichtbar sind. Das endgültige Recap muss entweder jedes bedeutungsvolle Element mit einem Block darstellen oder es absichtlich weglassen, weil es winzig, redundant oder nicht benutzersichtbar ist.
• Ein file-tree der geänderten Dateien mit dem change Flag jedes Eintrags, damit der Reviewer den Umfang der Arbeit auf einen Blick sieht.
• Der aufgeteilte diff der WICHTIGSTEN geänderten Dateien, gruppiert unter einer ## Key changes rich-text Überschrift in einem einzigen horizontalen tabs Block (der Standardausrichtung, eine Datei pro Tab), mit einer einzeiligen summary und einigen annotations zu jeder — damit der Reviewer von der hohen Flughöhe direkt in den tragenden Code abtauchen kann. Verwenden Sie horizontale Datei-Tabs, keine vertikale Seitenleiste, damit die ausgewählte Datei genügend Breite für den nebeneinander angeordneten Diff hat.

Überspringen Sie den Diff-Anhang nur bei einer wirklich winzigen Änderung, die sich als einfacher Diff schneller überprüfen lässt (siehe "Wann zu verwenden"); bei jeder Änderung, die ein Recap wert ist, gehören der Dateibaum und die Schlüsseländerungs-Diffs in den Plan.

Kanonische Struktur und Budgets

Ein starkes Recap folgt einem Gerüst von oben nach unten:

1. UI-Impact-Überschrift — zuerst Wireframes, wenn der Diff die gerenderte UI geändert hat.
2. Kurze Ergebnis-Erzählung (rich-text): Was hat sich geändert und warum, 1-3 Absätze.
3. data-model / api-endpoint Blöcke für Schema- und Vertragsänderungen.
4. file-tree der geänderten Dateien mit change Flags.
5. ## Key changes — ein horizontaler tabs Block von diff / annotated-code.

Budgets, die das Recap überprüfbar halten:

• 3-8 Schlüsseländerungs-Tabs. Weniger als 3 bei einer großen Änderung unterfordern den Reviewer; mehr als 8 hören auf, eine Zusammenfassung zu sein.
• Halten Sie jeden Diff/annotated-code Auszug fokussiert — bevorzugen Sie unter ~150 Zeilen pro Tab; fassen Sie den Rest einer langen Datei zusammen oder verlinken Sie ihn, anstatt ihn auszuspucken.
• Titel höchstens ~70 Zeichen; Kurzbeschreibung 1-3 Sätze.

Diese Budgets sind auch die Kostenobergrenze: Überschreiten Sie sie nicht im Namen der Gründlichkeit, und lesen Sie den vollständigen Diff nach dem anfänglichen sequentiellen Durchlauf nicht erneut — arbeiten Sie von den Notizen, die während dieses Durchlaufs gemacht wurden.

GUT. Eine 25-Dateien-Auth-Änderung: Vorher/Nachher Wireframes der Anmeldeoberfläche, eine zweizeilige Erzählung, ein diff-bewusstes data-model der Sessions-Tabelle, ein api-endpoint für die neue Refresh-Route, ein file-tree mit Änderungsflags und ## Key changes mit fünf fokussierten Tabs, jeder mit einer einzeiligen summary und einigen Annotationen zu den tragenden Hunk-Blöcken.

SCHLECHT. Ein riesiger, unsegmentierter Diff-Dump ohne Zusammenfassungen oder Annotationen; oder ein spärliches Drei-Block-Recap einer 40-Dateien-Änderung (ein Wireframe, ein Satz, eine Dateiliste), das den Reviewer dennoch zurück in den rohen Diff zwingt.

UI-Impact benötigt Wireframes

Wenn der Diff gerenderte UI, Layout, Dichte, visuellen Zustand, Interaktionsmöglichkeiten, Navigation, Steuerelemente, Menüs, Dialoge oder Design-Tokens ändert, MUSS das Recap ein oder mehrere Wireframes enthalten. Text und Datei-Diffs sind kein Ersatz dafür, zu zeigen, was sich visuell geändert hat.

Bevor Sie Wireframes auswählen, führen Sie eine UI-Abdeckungsprüfung aus dem Diff durch:

• Identifizieren Sie die Eintrittsoberfläche, auf der die Änderung erscheint, z. B. eine Seitenkopfzeile, Listenzeile, Symbolleiste, Route-Shell oder Menü-Trigger.
• Identifizieren Sie die Interaktionsfläche, die sich öffnet oder ändert, z. B. ein Popover, Dialog, Tab, Blatt, Dropdown, Inline-Editor oder Toast.
• Identifizieren Sie das resultierende Ziel oder den dauerhaften Zustand, z. B. eine öffentliche Seite, schreibgeschützte Ansicht, Leerzustand, Fehlerzustand, Ladezustand, Berechtigungsverweigerungszustand oder gespeicherter/geteilter Zustand.
• Identifizieren Sie Zugriffs- oder Rollenvarianten, wenn sich Berechtigungen ändern. Unterschiede zwischen Besitzer/Administrator/Editor und Betrachter/Nicht-Manager sind visuelles Verhalten und benötigen eine kompakte Matrix, gepaarte Wireframes oder eine klar beschriftete Zustandssequenz.

Bei UI-lastigen PRs reicht ein einzelnes Vorher/Nachher der Eintrittsoberfläche nicht aus. Zeigen Sie den geänderten Einstiegspunkt, die hauptsächlich geänderte Interaktionsfläche und den resultierenden/Zielzustand. Fügen Sie weitere Zustände hinzu, wenn der Diff Tabs, rollenbasierte Steuerelemente, öffentliche/private Sichtbarkeit, Einladungs-/Verwaltungsabläufe, destruktive Steuerelemente oder Leer-/Fehler-Verzweigungen hinzufügt.

Wählen Sie die kleinste visuelle Fläche, die das Review klar macht:

• Verwenden Sie ein Before / After Wireframe-Paar, wenn der Reviewer von einem direkten Vergleich profitiert, z. B. ein entferntes oder hinzugefügtes Steuerelement, einen geänderten Zustand, die Layoutdichte, die Reihenfolge, die Navigation oder eine sichtbare Komponentenersetzung. references/wireframe.md legt fest, wie dieses Paar angeordnet wird (Spalten vs. vertikaler Stapel nach Geometrie).
• Verwenden Sie ein Nur-Nachher-Wireframe, wenn die Änderung rein additiv ist oder der "Vorher"-Zustand nur Abwesenheit zeigen würde, ohne einen Review-Mehrwert zu bieten.
• Verwenden Sie mehr als zwei Wireframes, wenn die UI-Änderung flussabhängig, responsiv oder zustandsbehaftet ist; zeigen Sie die bedeutungsvollen Zustände der Reihe nach, anstatt ein einzelnes Vorher/Nachher-Paar zu erzwingen.
• Verwenden Sie für winzige Flächen wie Menüs, Popover, Dialoge, Toasts oder Panels die passende surface (popover, panel usw.) und zeigen Sie die fokussierte Unterfläche. Zeichnen Sie keine vollständige Seite neu, es sei denn, die Platzierung auf der Seite ist selbst Teil der Änderung.

Verankern Sie jedes Wireframe im geänderten UI-Verhalten, den Komponentennamen, Dateipfaden und diff-sichtbaren Beschriftungen/Zuständen. Wenn genaue Pixel geschätzt statt erfasst werden, sagen Sie dies in der Wireframe-Bildunterschrift oder einer prägnanten Annotation. Fügen Sie bei lokalen/manuellen Recaps die Planquelle, die die Wireframes enthält, importieren Sie sie neu oder aktualisieren Sie sie, sodass das gerenderte Recap mit der verfügbaren UI-Visualisierung geöffnet wird.

Wireframe-Qualität — lesen Sie references/wireframe.md

UI-Recap-/Plan-Wireframes müssen eine strenge Qualitätsschwelle erfüllen — vollbreites Chrome, fixierte untere Leisten, echte Produktinhalte, Vorher/Nachher-Vergleichbarkeit, die richtige surface Voreinstellung, --wf-* Tokens anstelle von Hex und keine <html>/<style>/Schriftart-Tags. Bevor Sie IRGENDEIN Wireframe / <Screen> / WireframeBlock erstellen, lesen Sie references/wireframe.md in diesem Skill-Verzeichnis — es ist die einzige Quelle der Wahrheit für die HTML-Wireframe-Qualität, die Wort für Wort mit /visual-plan und /visual-recap geteilt wird. Erstellen Sie keine Wireframes aus dem Gedächtnis.

Verwenden Sie das Standardformat WireframeBlock / <Screen>, damit der Plan-Betrachter den Oberflächenrahmen, das Thema und den Skizzen-/Klarschalt-Umschalter besitzt. HTML-Wireframes sind geeignet, wenn die Platzierungsgenauigkeit wichtig ist, insbesondere bei Popovern, Menüs, Dialogen und dichten Formularen. Lassen Sie bei HTML-Wireframes renderMode entweder nicht gesetzt oder auf wireframe, es sei denn, ein reiner Design-Mockup (bearbeitbar) wird explizit benötigt, weil renderMode="design" die skizzenhafte grobe Überlagerung deaktiviert.

Wenn ein Browser-Tool verfügbar ist, rendern Sie ein UI-Impact-Recap im Plan-Betrachter und prüfen Sie es vor dem Teilen visuell im aktuellen Thema. Wenn sich eine Beschriftung, Annotation, Symbolleiste oder ein Wireframe-Inhalt mit einem anderen Element überschneidet, korrigieren Sie das MDX und importieren Sie es neu, bevor Sie den Link melden. Beschränken Sie dies auf einen Render-und-Prüf-Durchlauf plus höchstens eine Korrektur-und-Neu-render; iterieren Sie nicht darüber hinaus, es sei denn, der Benutzer fordert es ausdrücklich an. Ein Textabgleich-Screenshot ist nicht ausreichend; prüfen Sie das aufgenommene Bild visuell. Wenn kein Browser verfügbar ist (z. B. ein kopfloser CI-Agent), geben Sie dies stattdessen in der Recap-Übergabe an.

Top-Leinwand-Recaps — lesen Sie ../visual-plan/references/canvas.md

Wenn ein Recap eine obere Leinwand, ein Storyboard oder eine Flussansicht enthält, lesen Sie ../visual-plan/references/canvas.md, bevor Sie canvas.mdx erstellen. Recap-Leinwand-Zeichenflächen müssen denselben HTML-Wireframe-Pfad wie gute Dokumentkörper-Wireframes verwenden: <Screen surface="..." html={...} /> mit einem semantischen HTML-Fragment. Erstellen Sie keine neuen Kit-Baum-Kinder wie <FrameScreen>, <Card>, <Row>, <Title> oder <Btn> innerhalb von Leinwand-<Screen>-Tags. Diese Komponenten sind Legacy-Kompatibilitätsmarkup für alte Pläne; in neuen Leinwand-Storyboards können sie selbst dann beengte oder überlappende Layouts erzeugen, wenn das Inline-Body-Wireframe gut aussieht. Wenn ein Leinwand-Mockup schlechter aussieht als derselbe Bildschirm unterhalb der Falte, nehmen Sie an, dass es den Legacy-Kit-Pfad verwendet hat, und ersetzen Sie es durch einen HTML-Bildschirm.

Öffnen und Melden des Recaps

Führen Sie im lokalen Dateien-Datenschutzmodus zuerst plan local check aus, melden Sie dann die lokale Bridge-URL von npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open oder von <plan-dir>/.plan-url. Es öffnet die gehostete Plan-UI, liest aber von der Localhost-Bridge auf diesem Rechner, ist also nicht über Rechner hinweg teilbar. Wenn die Plan-App selbst lokal mit demselben PLAN_LOCAL_DIR ausgeführt wird, ist die Route /local-plans/<slug> ebenfalls gültig. Erfinden Sie keine gehostete Datenbank-URL und veröffentlichen Sie nicht nur, um einen absoluten Plan-Link zu erhalten.

Nach der Erstellung des Recaps verlinken Sie den Reviewer zum gerenderten Plan mit einer absoluten URL auf dem Ursprung, dessen Datenbank den Plan tatsächlich enthält. Dieser Ursprung ist der Plan MCP Server, über den Sie gerade das Recap erstellt haben — NICHT irgendein Dev-Server, von dem Sie zufällig wissen, dass er läuft. Das Erstellungswerkzeug gibt den korrekten Link zurück; melden Sie DIESEN. Machen Sie niemals eine lokale plan.mdx-Datei, einen lokalen Spiegelordner oder einen relativen Pfad wie /plans/<id> zum primären Link.

Wenn das Recap in einem PR für ein privates Repository veröffentlicht wird, darf der Plan-Link nicht auf einer öffentlichen Domain sein. Wenn der Plan MCP Server für private Repositories eine andere Basis-URL verwendet, geben Sie diese aus. Öffnen Sie den Plan, um zu bestätigen, dass die Anmeldung mit dem richtigen Repository-Konto funktioniert, wenn die Sichtbarkeit unklar ist.