Website-Copy-Review: Review-Dokument aus Codebasis extrahieren

Verwandle eine Website-Codebasis in ein Dokument, das ein nicht-technischer Prüfer Seite für Seite lesen und mit Anmerkungen versehen kann – wobei jeder Textstring eine Adresse (einen Referenzcode) behält, sodass seine Änderungen mechanisch in die Quelle zurückgespielt werden können.

Warum es so gebaut ist

Website-Content ist keine Prosa. Es sind hunderte kurze Strings in festen Layout-Slots innerhalb von Markup. Daher:

Ein Prosa-Dump mit Änderungsverfolgung kommt als unklarer Wust von Einfügungen zurück, die nicht ohne Rätselraten in das Markup zurückgesetzt werden können. Daher: eine Zeile pro String, mit einem Referenzcode.
Ein Prüfer, der aus einer 4-Wort-Kartenüberschrift 12 Wörter macht, zerstört das Layout und kann das in Word nicht sehen. Daher: Zeichenanzahlen und einfach verständliche Längenempfehlungen bei platzbegrenzten Zeilen.
Prüfer sehen nie den Code. Daher sagt jede Zeile in einfachen Worten, was sie ist („Button-Label“, „Alt-Text“), und jeder Seitenabschnitt sagt, wo er auf der Live-Site lebt.

Das Dokument muss pro Seite von oben nach unten lesbar sein (damit Ton und Erzählfluss beurteilt werden können), während jeder String einzeln adressierbar bleibt.

Mitgelieferte Dateien

scripts/merge_and_verify.py, scripts/build_review_docx.py, references/extraction-brief.md und assets/pages.example.json liegen neben dieser Datei. Fehlen sie (weil das Skill nur als SKILL.md installiert wurde), suche in ~/my-skills/website-copy-review/ oder im Repository brianitsup/website-copy-review; ist keines erreichbar, teile dies dem Benutzer mit, anstatt das Dokumentenlayout zu improvisieren – es darf zwischen Durchläufen nicht variieren.

Grundregeln

Schreibgeschützt. Bearbeite niemals das Repository. Die gesamte Ausgabe erfolgt in das Scratchpad, es sei denn, der Benutzer wünscht sie im Repository.
Installiere python-docx in einer virtuellen Umgebung im Scratchpad, nicht global: python3 -m venv <scratch-pad>/venv && <scratch-pad>/venv/bin/pip install python-docx
Berichte ehrlich. Wenn eine Datei nicht geparst werden konnte oder eine Prüfung nicht ausgeführt werden konnte, sage dies; verkleinere stillschweigend nie den Umfang.
Wenn das Repository eine Issue-First-ähnliche Workflow-Konvention in AGENTS.md, CLAUDE.md, PROJECT_WORKFLOW.md oder CONTRIBUTING.md hat, teile dem Benutzer mit, dass die zurückgegebenen Änderungen und etwaige Mängel vor der Implementierung einen Issue erfordern. Eröffne keinen ungefragt.

Erwarte den Umfang: Eine mittelgroße Broschüren-Site hat etwa 400–600 Einträge auf 15–20 Seiten, ein 50–60-seitiges Dokument. Das ist normal; Seitentabellen pro Seite halten es navigierbar.

Schritt 1 – Umfang klären (einmalig nachfragen, mit Vorgaben)

Frage diese zusammen (sofern AskUserQuestion verfügbar), mit Empfehlung der Vorgabewerte:

Welcher Text? Nur hartcodierter Text in Templates/Komponenten (Vorgabe – Editor-Content kann im CMS ohne Codeänderung korrigiert werden), oder auch CMS-verfasste Beiträge/Seiten?
Wie werden Prüfer Änderungen markieren? Leere Spalte „Vorgeschlagene Korrektur“ (Vorgabe – eindeutig und mechanisch anwendbar), oder Word-Kommentare/Änderungsverfolgung (natürlich, aber schwer zurückzuspielen).
Welcher Content-Stand? Arbeitsbaum (Working Tree) oder Live/Produktion? Weise darauf hin, dass eine lokale Datenbank oder ein Content-Snapshot möglicherweise hinter dem tatsächlich Veröffentlichten hinterherhinkt.

Wenn der Benutzer abwesend ist, wähle die Vorgabewerte und teile dies oben im Bericht mit. Die Antworten landen auf der Titelseite (im meta.scope-Block von pages.json).

Schritt 2 – Herausfinden, wo Texte leben

Gehe nicht von einem bestimmten Stack aus. Untersuche das Repository (package.json, Theme-Manifeste, Framework-Konfiguration, Verzeichnisstruktur) und liste die Quellen auf:

Im Code: .hbs, JSX/TSX, Vue, Svelte, Astro, Blade, ERB, Twig, PHP-Themes, HTML, Markdown/MDX-Content-Dateien, i18n/locale JSON oder YAML.
Außerhalb des Codes: CMS-Datenbank/API (Ghost, WordPress, Sanity, Contentful, Strapi) und besucherorientierte Site-Einstellungen, die nicht im Repository sind – Site-Titel, Meta-Beschreibung, Navigationslabels, CTA/Button-Labels, die im Admin gesetzt sind. Wenn du diese abrufst, speichere den rohen Export in <scratch-pad>/snapshots/, damit sie wie jede andere Quelle verifiziert werden können (siehe Schritt 4).

Erwische immer diese leicht übersehenen Kategorien, jede beschriftet, damit Prüfer wissen, was sie sehen: alt-Texte (Screenreader und Suchmaschinen lesen sie – Partner-/Produktnamen müssen stimmen), aria-label, Formular-Platzhalter, Submit-Labels, Erfolgs-/Fehler-/Validierungsmeldungen, Leerzustände, 404/Fehlerseiten, Copyright-Zeilen und rechtliche Footer.

Bilde jede Seitenvorlage auf ihren Live-URL-Pfad ab (routes.yaml, dateibasiertes Routing, Router-Konfiguration, CMS-Seite→Template-Zuordnungen). Wenn eine Vorlage keine Seite oder Route hat, sage dies ausdrücklich in der Notiz dieser Seite – der Text ist unerreichbar, und Prüfer sollten das wissen, bevor sie Zeit darauf verwenden.

Schreibe dann <scratch-pad>/pages.json basierend auf assets/pages.example.json: ein Eintrag pro Seite in der Reihenfolge, die das Dokument präsentieren soll, mit key, title, url, source, optional note, plus dem meta-Block (Projekt, Umfangsentscheidungen, Ausschlüsse, Vorlagen ohne hartcodierten Text). Das Build-Skript liest dies – Seiten-Metadaten werden nie hartcodiert.

Schritt 3 – Parallel extrahieren mit einem festen Vertrag

Erfasse zuerst die gesamte Oberfläche: jede Seitenvorlage und jedes Partial/Shared-Component, das diese Seiten einbinden (Header, Footer, Karten, Newsletter-Formulare, CTAs). Partials sind das, was verloren geht, wenn Dateien auf mehrere Agenten aufgeteilt werden.
Teile in nicht überlappende Gruppen auf (etwa 3–6 Dateien oder ~1.500 Zeilen pro Gruppe) und weise jede Datei explizit zu. Geteilte Partials erhalten einen eigenen Seiten-Eintrag (z. B. FOOTER, NAV) mit dem Hinweis, dass sie siteweit erscheinen, anstatt unter jeder Seite wiederholt zu werden.
Starte einen Unteragenten pro Gruppe, in einer einzigen Runde, auf einem mittleren Modell (z. B. Sonnet): Die Arbeit ist mechanisch, aber Auslassungen sind unsichtbar und fatal. Füge references/extraction-brief.md wortwörtlich in jede Eingabeaufforderung ein, gefolgt von der Dateiliste des jeweiligen Agenten, dem zu verwendenden page_key für jede Datei, dem Repository-Stammverzeichnis und dem Ausgabepfad <scratch-pad>/extract/<gruppe>.json.
Wenn sie zurückkommen, bestätige, dass jede aufgelistete Datei in einer Ausgabe erscheint (oder als textfrei gemeldet wurde). Weise alles Fehlende neu zu.

Sammle die gemeldeten Beurteilungsentscheidungen jedes Agenten; du wirst sie in Schritt 4 und im Abschlussbericht benötigen.

Schritt 4 – Unabhängig zusammenführen und verifizieren (nicht überspringen)

Selbstprüfungen von Agenten sind keine Verifikation. Führe aus:

<venv>/bin/python scripts/merge_and_verify.py \
  --extract-dir <scratch-pad>/extract --pages <scratch-pad>/pages.json \
  --repo <repository-stamm> [--snapshot-dir <scratch-pad>/snapshots] --out <scratch-pad>/out

Dieses Skript führt alle Extraktionen in der Reihenfolge von pages.json zusammen, weist PAGEKEY-NN-Referenzen zu, berechnet chars neu und prüft jeden String gegen seine Quelldatei mit drei zunehmend großzügigeren Normalisierungen – roh (Leerzeichen reduziert), tag-bereinigt, leerzeichen-glatt – denn jede fängt etwas anderes ein (Attributtext besteht den Rohtest und fällt beim tag-bereinigten Test konstruktionsbedingt durch; das ist erwartet). Es stellt außerdem sicher, dass es keine doppelten Referenzen, keinen leeren Text und dass jedes page_key in pages.json existiert. Ausgaben: items.json, copy-review-manifest.csv, verification.md.

Der Exit-Code ist ungleich Null, solange etwas ungelöst ist. Öffne für jede UNMATCHED-Zeile die Quelle und suche. Legitime Residuen sind normalerweise konditionale/schleifenförmige Blöcke, in denen der Agent den gerenderten Text statt eines Literal-Substrings aufgezeichnet hat – bestätige, dass er wie aufgezeichnet gerendert wird, liste ihn dann in <scratch-pad>/accepted.json als {"REF": "grund"} und führe mit --accept <scratch-pad>/accepted.json erneut aus. Behebe echte Fehler im Extraktions-JSON (nicht im Repository) und führe erneut aus. Referenzen werden beim Zusammenführen zugewiesen, also korrigiere die Daten, führe dann erneut aus, dann baue.

Überprüfe auch stichprobenartig die Vollständigkeit: Nimm zwei oder drei der dichtesten Dateien und vergleiche die Anzahl der Einträge mit einem kurzen Durchlesen der Datei. Fehlende Strings tauchen in keiner automatischen Prüfung auf.

Schritt 5 – Das Dokument erstellen

<venv>/bin/python scripts/build_review_docx.py \
  --pages <scratch-pad>/pages.json --items <scratch-pad>/out/items.json \
  --out <scratch-pad>/out/<Projekt>-Website-Copy-Review.docx

Das Skript besitzt das Layout, sodass es zwischen Durchläufen nie variiert: Querformat A4, 1,4 cm Ränder; Titelseite (Umfang, was enthalten/nicht enthalten ist, Prüfhinweise, längenbegrenzte Zeilen nahe ihrer Länge halten, Referenzen nicht umnummerieren oder löschen, Fakten prüfen – Jahre, Mitarbeiterzahlen, Zahlen, Partnernamen, Berufsbezeichnungen – ebenso sorgfältig wie Formulierungen); Inhaltsverzeichnis mit Summen und leeren Vorlagen; ein Abschnitt pro Seite auf einer neuen Seite; Spalten Ref 2,2 / Element 4,3 / Aktueller Text 8,4 / Vorgeschlagene Korrektur 8,4 / Notizen 3,6 cm; dunkle sich wiederholende Kopfzeile; getönte Großbuchstaben-Abschnitts-Bannerzeilen; Streifenmuster; Zeichenanzahl-Hinweise bei platzbegrenzten Zeilen; getönte Zellen und ein Warnhinweis „Den Teil {{…}} behalten“ bei dynamischen Zeilen; Abschlussseite mit nächsten Schritten und einer Abnahmetabelle. Es öffnet die Datei erneut und bestätigt, dass die Zeilenanzahl übereinstimmt und die Korrektur-/Notizenspalten leer sind.

Fülle niemals „Vorgeschlagene Korrektur“ oder „Notizen“ vor. Das Urteil des Prüfers ist der Punkt.

Wenn der Benutzer in Schritt 1 Word-Kommentare/Änderungsverfolgung gewählt hat, erstelle trotzdem dieses Dokument (die Referenzcodes machen die Änderungsverfolgung nachvollziehbar) und teile ihm mit, dass Änderungen möglicherweise manuell zugeordnet werden müssen.

Schritt 6 – Vor der Auslieferung ansehen

Strukturprüfungen belegen, dass die Daten korrekt sind, nicht, dass sie gut lesbar sind. Rendere und betrachte tatsächlich: die Titelseite, eine Einstellungs-/Navigationsseite und die dichteste Seite mit langen Absätzen (wo Breiten versagen).

soffice --headless --convert-to pdf --outdir <verz> <datei>.docx
pdftoppm -png -r 80 -f <n> -l <n> <datei>.pdf <präfix>

Öffne die PNGs mit Read. Fehlen diese Werkzeuge, sage klar, dass keine visuelle Prüfung stattgefunden hat.

Schritt 7 – Quellfehler getrennt melden

Das Lesen jeder Zeile von Markup fördert echte Fehler zutage. Melde sie in einem separaten Abschnitt (oder einer separaten source-defects.md) – es sind Code-Probleme, keine Formulierungsprobleme. Häufige:

Wörtliches Markdown in gerendertem HTML (**fett** wird auf der Seite angezeigt)
Ankerlinks zu IDs, die nirgendwo existieren
Links zu Abschnitten, die existieren, aber nichts Sinnvolles enthalten
Vorlagen ohne Seite/Route, sodass ihr Text unerreichbar ist
Verwalteter CMS-Content hinter einer benutzerdefinierten Vorlage, die ihn überschreibt
Platzhalterwerte, die in wiederverwendbaren Vorlagen hartcodiert sind

Überprüfe jeden selbst, bevor du ihn meldest – suche mit grep nach der Ziel-ID, öffne die Vorlage. Agenten übertreiben diese: Ein „kaputter Anker“ entpuppte sich einst als ein gültiges Ziel, dessen Abschnitt einfach nichts zu handeln hatte. Beschreibe, was tatsächlich vorhanden ist, mit Datei und Zeile.

Schritt 8 – Ausliefern

Sende die .docx an den Benutzer. Erwähne kurz: Gesamtanzahl Einträge und Seiten, die getroffenen Umfangsentscheidungen, das CSV-Manifest (zum Anwenden zurückgegebener Änderungen per Referenz – halte es dem Prüfer vor), etwaige verifizierungsrelevante Reste, die du akzeptiert hast und warum, die Mängelliste und den Issue-First-Hinweis, falls das Repository diese Konvention hat.

Anwenden zurückgegebener Korrekturen (wenn der Benutzer zurückkommt)

Lese die zurückgegebenen .docx-Tabellenzeilen (Ref + Vorgeschlagene Korrektur + Notizen), verknüpfe mit copy-review-manifest.csv über Ref, und ersetze für jede nicht leere Korrektur text in file nahe line. Markiere anstatt stillschweigend zu kürzen jede Korrektur, die weit über ihrer chars auf einer platzbegrenzten Zeile liegt, und jede, die einen {{…}}-Ausdruck entfernt. Zeige dem Benutzer die geplanten Änderungen, bevor du das Repository bearbeitest.

Website-Copy-Review

Was ist Website-Copy-Review?

In Ihrer bevorzugten KI fragen

Dokumentation