Ephasme/dokument-verfeinern

Dokument verfeinern

Nimm ein Dokument und erstelle eine Version, auf die ein Leser ohne Vorgeschichte mit dem Projekt handeln kann: legacy-frei, faktenbasiert, prägnant, organisiert und auf den erklärten Leser zugeschnitten.

Vier Durchläufe, feste Reihenfolge, dann ein Verifikationsschritt. Alles Entfernte wird in eine Aufzeichnungsdatei geschrieben, sodass eine falsche Entscheidung rückgängig gemacht werden kann.

Aufruf

refine-document <pfad> [--target=agent|human] [--no-record]

Flag	Standard	Wirkung
--target	agent	Für welchen Leser der letzte Durchlauf optimiert. Ändert das Dokument, nicht nur den Ton – siehe Durchlauf 4.
--no-record	aus	Überspringe die Aufzeichnungsdatei. Entfernungen werden nur noch über die Versionsverwaltung wiederherstellbar.

Vor dem Berühren der Datei:

1. Bestätige, dass die Anfrage dieses Dokument nennt. Dies überschreibt die Datei des Benutzers an Ort und Stelle.
2. Bestätige, dass die Datei in der Versionsverwaltung verfolgt und bereinigt ist. Wenn nicht, teile dies mit und hole eine explizite Bestätigung ein – unter --no-record ist dies der letzte verbleibende Wiederherstellungspfad.
3. Nenne das Ziel, mit dem du arbeitest, in deiner ersten Nachricht, auch wenn es der Standard ist. Ein stiller Standard führt dazu, dass ein Dokument für den falschen Leser geformt wird.
4. Mehrere Dokumente: Führe diesen Vorgang einmal pro Dokument aus, jeweils mit einem Unter-Agenten, wenn Unter-Agenten verfügbar sind, und übergib denselben Zielparameter und dieselben Flags an jeden. Ein Unter-Agent besitzt genau eine Datei.

Ausgaben

Ausgabe	Pfad	Inhalt
Verfeinertes Dokument	der ursprüngliche Pfad, direkt überschrieben	nur aktueller Zustand, zielgerecht geformt
Aufzeichnung	{name}.changelog.md, gleiches Verzeichnis	alles Entfernte, wortwörtlich, lokalisiert – läuft über Läufe hinweg an
Bericht	deine Antwort	siehe Bericht

Durchlaufreihenfolge

Führe die Durchläufe in dieser Reihenfolge aus, als vier separate Lesevorgänge des Dokuments. Jeder verkleinert die Eingabe für den nächsten, und in falscher Reihenfolge machen sie sich gegenseitig zunichte – das Komprimieren von Prosa, die Durchlauf 1 löschen würde, verschwendet Arbeit, und das Organisieren vor dem Komprimieren organisiert Füllstoff.

1. Altlasten entfernen – alles entfernen, das nur als Verweis auf die Vergangenheit Sinn ergibt.
2. Faktenbasiert – jede verbleibende Behauptung wird überprüft, zitiert oder markiert.
3. Prägnant – eine Tatsache, ein Ort, kürzeste Form, die die Tatsache bewahrt.
4. Organisieren – Kritisches zuerst, dann die Form des Ziels.

Durchlauf 1 – Altlasten entfernen

ERFORDERLICHE UNTERFÄHIGKEIT: Verwende strip-legacy-content für diesen Durchlauf. Sie besitzt die Taxonomie der Altlasten, die Regel "Ausschneiden, nicht Umschreiben" und das Format {name}.changelog.md, in das diese Fähigkeit ebenfalls schreibt. Bilde --no-record auf ihr --no-changelog ab.

Wo diese Fähigkeit nicht verfügbar ist, entferne: Geschichts- und Entwicklungsnarrative, Entscheidungsaufzeichnungen und ADRs, Abkündigungshinweise, Migrations- und Upgrade-Anleitungen, eingebettete Änderungsprotokolle und Versionshinweise, Abwärtskompatibilitätsabschnitte, abgelehnte Alternativen, datierte Kommentare, überholte Abschnitte. Schneide die Textabschnitte aus; schreibe die verbleibende Prosa nicht um – Durchläufe 2-4 erledigen das.

Die Regel für veraltete Funktionen. Eine als veraltet markierte Funktion ist nicht automatisch eine Altlast. Wende diesen Test an und notiere, welchen Zweig du gewählt hast:

Hat die Funktion eine Verwendung, die nicht "Unterstützung des alten Systems" ist?

• Nein – sie existiert nur für Abwärtskompatibilität. Entferne die Funktion und ihren Hinweis.
• Ja – es ist aktuelles Verhalten. Behalte sie, entferne den Entfernungszeitplan und die "seit v1"-Rahmung und markiere sie in der Aufzeichnung.

Durchlauf 2 – Faktenbasiert

Jede Aussage, die das Dokument macht, ist eine Behauptung, einschließlich derer, die es geerbt hat. Klassifiziere jede und ergreife die passende Maßnahme. Es gibt keine fünfte Option.

Klasse	Signal	Aktion
Überprüfbar, Artefakt erreichbar	Verhalten, Flags, Standardwerte, Pfade, Befehle, Konfigurationsschlüssel, und du kannst den Code, die Konfiguration oder die --help-Ausgabe lesen	Überprüfe es. Wahr: behalten. Falsch: korrigieren.
Überprüfbar, Artefakt nicht erreichbar	dieselben Behauptungen, ohne Repo, Binärdatei oder Dokumentation zum Abgleich	Behalte die Behauptung genau so, wie die Quelle sie angibt, unmarkiert, und liste sie im Bericht als ungeprüft auf.
Extern belegbar	Standards, Protokollverhalten, Drittanbieter-Produktverhalten, Versionsunterstützung	Zitiere die Primärquelle inline mit ihrem Datum oder ihrer Version. Keine akzeptable Quelle: entferne die Behauptung.
Vergleichend oder werblich	"10x schneller", "branchenführend", "rasend schnell", "elegant", "die meisten Ingenieure sind sich einig", und jeder Vergleich, dessen anderer Begriff nicht Teil des aktuellen Systems ist ("leichter als Kafka")	Schneide es aus, es sei denn, es existiert eine zitierfähige Messung – dann nenne die Messung und ihre Quelle. Behalte die verbleibende Tatsache: "reiht Jobs mit Redis Streams ein".
Nicht überprüfbar und gefährlich	eine ungeprüfte Behauptung, auf die ein Leser unwiderruflich handeln könnte: Datenverlust, Ausgaben, Anmeldeinformationen, ein destruktiver Befehl, eine Sicherheitsgrenze	Behalte sie, markiere sie im Dokument mit [unverifiziert] und liste sie im Bericht auf.

Die Markierung gilt für Gefahren, nicht für die Herkunft. Ein Dokument über ein Artefakt, das du nicht erreichen kannst, besteht hauptsächlich aus ungeprüften Behauptungen, und das Markieren jeder einzelnen lehrt den Leser, die Markierung zu überspringen. Nicht überprüfte Herkunft gehört in den Bericht und die Aufzeichnung; [unverifiziert] im Dokument ist für die Behauptungen reserviert, deren Fehlschlag der Leser nicht rückgängig machen kann. Wenn mehr als eine Handvoll Markierungen im Dokument überleben, hast du Herkunft als Gefahr eingestuft – klassifiziere neu.

Erfinde niemals eine Tatsache, die das Quelldokument nicht hatte. Keinen Konfigurationsspeicherort, keinen Standardwert, kein Dateiformat, keine Voraussetzung – nicht einmal eine, die mit ziemlicher Sicherheit wahr ist. Eine stillschweigend abgeleitete Tatsache ist von einer überprüften nicht zu unterscheiden, und dieser Durchlauf ist das einzige, was zwischen dem Leser und einer selbstbewusst falschen Antwort steht. Wenn die Quelle schweigt, schweigt das verfeinerte Dokument.

Weiche eine unbelegte Behauptung niemals in eine vage auf. "Etwa 10x schneller" umgeschrieben als "sehr schnell" ist dieselbe Meinung mit weniger Präzision. Zitiere sie oder schneide sie aus.

Lösche niemals eine Handlungsanweisung mangels Quelle. Markieren ist besser als Löschen: eine markierte Anweisung kann von jemandem überprüft werden, der Bescheid weiß, eine gelöschte ist weg.

Für ein Dokument, dessen Behauptungen größtenteils extern sind, führe cite-or-refuse für die Quellenangabe und fact-check-document für eine vollständige Prüfung aller Behauptungen aus, bevor du fortfährst.

Durchlauf 3 – Prägnant

Eine Tatsache, ein Ort. Wähle für jede Tatsache den einzelnen Abschnitt, in dem ein Leser, der danach sucht, als Erstes ankommen wird. Nenne sie dort vollständig. Überall sonst lösche entweder die Wiederholung oder ersetze sie durch einen Verweis, der diesen Abschnitt genau benennt.

Lösche direkt:

• Füllwort-Einleitungen: "Es ist erwähnenswert, dass", "Einfach", "Im Grunde", "Wie man sieht".
• Anweisungen, das zu tun, was der Leser bereits tut: "Um zu installieren, führe den Installationsbefehl aus".
• Wiederholte Abschnittsüberschriften als erste Sätze.
• Abwehrende Einschränkungen, die keine Handlung ändern.
• Beispiele, die dasselbe wie ein früheres Beispiel demonstrieren.

Komprimiere:

• Mehr als drei Elemente, die über mehr als zwei Attribute verglichen werden → eine Tabelle.
• Ein Absatz, der parallele Dinge auflistet → eine Liste.
• Ein Satz, dessen Subjekt eine Nominalisierung ist → das Verb ("eine Entscheidung treffen" → "entscheiden").

Die Kompressionsuntergrenze. Höre auf, wenn das Entfernen des nächsten Wortes eine Tatsache entfernt. Ein kürzeres Dokument, das eine Tatsache verloren hat, ist ein Rückschritt, kein Gewinn. Die Wortanzahl ist ein Symptom der Arbeit, niemals ihr Ziel.

Die einzig bedingt erlaubte Duplikation ist die Kopf-und-Schwanz-Wiederholung des kritischen Blocks für das Agentenziel, jenseits des in Durchlauf 4 festgelegten Längenschwellenwerts. Unterhalb dieses Schwellenwerts ist es eine Wiederholung wie jede andere und fällt weg.

Durchlauf 4 – Für den erklärten Leser organisieren

Gemeinsam: das Ordnungsgesetz

Ordne nach dem, was den Leser blockiert, nicht nach der Geschichte des Themas:

1. Was dies ist – ein Satz, kein Vorwort.
2. Voraussetzungen, die alles andere blockieren – die Umgebungsvariable, ohne die nichts startet, die Anmeldeinformationen, die erforderliche Version.
3. Destruktive und irreversible Operationen – alles, was löscht, überschreibt, Geld ausgibt oder nicht rückgängig gemacht werden kann. Dies ist eine Platzierung nach Konsequenz, nicht nach Thema: es gehört ganz nach oben, auch wenn der Befehl obskur ist, und es wird markiert, nicht nur erwähnt.
4. Der Hauptpfad – das, wofür die meisten Leser gekommen sind, von Anfang bis Ende.
5. Alles andere zuerst das am häufigsten Verwendete.
6. Grenzfälle, Fehlerbehebung und Referenztabellen zuletzt.

Ein Zusammenfassungsblock gehört nach oben, wenn das Dokument mehr als etwa fünf Abschnitte hat; er listet die Fakten auf, die ein Leser braucht, bevor er irgendetwas tun kann, nicht eine Zusammenfassung der Prosa.

--target=agent

Der Leser ist ein Modell, das das Dokument als Kontext lädt, oft nachdem es nach einem einzelnen Begriff gesucht hat und nur den passenden Ausschnitt liest. Erstelle ein Dokument mit dieser Form:

1. Ein kritischer Block immer zuerst, identisch nur am Ende ab ~100 Zeilen. Voraussetzungen, destruktive Operationen und harte Einschränkungen kommen zuerst, unabhängig von der Länge. "Lost-in-the-middle"-Verschlechterung (Liu et al., TACL 2024) wird für Mehrdokumentenkontexte im Bereich von Tausenden bis Zehntausenden von Token gemessen – ein Dokument, das kurz genug ist, um in einem Lesevorgang gelesen zu werden, hat in diesem Sinne keine "Mitte", und eine Schwanzkopie ist dort reine Duplikation ohne Abrufnutzen. Dupliziere nur, wenn das Dokument denselben Schwelch von ~100 Zeilen überschreitet, der ihm auch ein Inhaltsverzeichnis (#9 unten) einbringt, wo ein "Grep-und-Ausschneiden"-Leser plausibel in der Mitte landen und den Block verpassen kann. Unterhalb des Schwellenwerts nenne es einmal, oben, und höre auf – eine zweite Kopie dort ist ein Rückschritt, den Durchlauf 3 hätte abfangen sollen, kein Merkmal dieses Ziels. Wenn es gerechtfertigt ist: überschreibe die erste Kopie mit ## Kritische Einschränkungen und die letzte mit ## Kritische Einschränkungen (wiederholt) – zwei eindeutige Anker, ein identischer Textkörper, die einzige annähernd doppelte Überschrift, die das Dokument enthalten darf.
2. Positive Formulierung. Nenne die durchzuführende Handlung. Wo ein Verbot wirklich nötig ist, setze die positive Alternative in denselben Satz: "schreibe nach state/, nicht nach /tmp". Modelle handhaben negierte Aussagen nachweislich schlechter als bejahende.
3. Eine Überschrift, eine abrufbare Einheit. Jede Überschrift ist innerhalb des Dokuments eindeutig, wörtlich und besteht aus den Wörtern, nach denen ein Agent grep-en würde – abgesehen vom Paar des kritischen Blocks oben. Ihr Abschnitt steht für sich: kein "wie oben beschrieben", kein Pronomen, dessen Bezug in einem anderen Abschnitt liegt.
4. Wörtliche Bezeichner am Verwendungsort. Vollständige Pfade, genaue Befehlszeilen, genaue Namen von Umgebungsvariablen, genaue Dateinamen – jedes Mal, nicht einmal mit Verweisen danach.
5. Überprüfbare Aussagen statt Erzählung. Ein Befehl, ein Pfad, ein Wert, eine Austrittsbedingung. Wenn ein Satz nicht überprüft werden kann, ist es wahrscheinlich eine Begründung – behalte ihn nur, wenn er ändert, was der Agent tut.
6. Nur Markdown-Struktur – Überschriften, Listen, Codeblöcke, kleine Tabellen. Füge kein XML-Tagging-Schema zu einem Markdown-Dokument hinzu; reserviere JSON- oder YAML-Blöcke für Inhalte, die echt maschinenlesbare Daten sind.
7. Kürzeste Form, die jede Tatsache bewahrt. Die Eingabelänge verschlechtert das Abrufen an sich, und thematisch benachbarte Inhalte, die nichts beantworten, wirken als Ablenkung – Beinahe-Prosa ist schlimmer als Abwesenheit.
8. Keine Widersprüche. Zwei Aussagen, die sich widersprechen, sind schlimmer als keine. Löse sie vor dem Schreiben auf.
9. Ein Inhaltsverzeichnis nur ab ~100 Zeilen, da der Agent möglicherweise einen Ausschnitt und nicht die gesamte Datei liest und sonst den Umfang nicht sehen kann.

Akzeptanzkriterium: Ein Agent, der nach einer Überschrift greppt und nur diesen Abschnitt liest, handelt korrekt.

--target=human

Der Leser scannt, bevor er liest, und liest nur eine Minderheit der Wörter. Wenn die Formatierung keine Hinweise bietet, degeneriert dieser Scan zu einer F-förmigen Bewegung am linken Rand entlang – Struktur verhindert dies, nicht ahmt es nach. Erstelle ein Dokument mit dieser Form:

1. Der Punkt im ersten Satz des Dokuments und jedes Abschnitts. Wichtigster Inhalt in den ersten beiden Absätzen; ein Leser, der dort aufhört, hat, wofür er gekommen ist.
2. Frontgeladene Zeilen. Jede Überschrift, jeder Aufzählungspunkt und jeder Absatz beginnt mit seinen informationstragenden Wörtern – die ersten beiden Wörter einer Zeile werden gelesen, der Rest wird gescannt.
3. Beschreibende Überschriften: "Konfiguriere das Statusverzeichnis", niemals "Überblick", "Anmerkungen", "Details" oder "Abschnitt 3".
4. Eine Idee pro Absatz, höchstens etwa vier Sätze.
5. Objektive Sprache. Neutrale Formulierung übertrifft werbliche Formulierung nachweislich in der Benutzerfreundlichkeit; dies ist ein Verständnisergebnis, keine Stilpräferenz.
6. Tabellen für Vergleiche, Prosa für Begründungen. Mehr als drei Elemente über mehr als zwei Attribute → Tabelle. Zusammenhängende, kausale oder nuancierte Erklärungen bleiben Prosa – das Zerstückeln eines Arguments in Aufzählungspunkte verliert die Verbindungen.
7. Domänenvokabular bleibt. Definiere einen Begriff einmal inline bei der ersten Verwendung. Vereinfache keine technische Präzision weg und schreibe nicht auf einen Lesbarkeitsformel-Score um – diese Scores können Organisation nicht sehen und bestrafen korrekte Terminologie.
8. Ein Inhaltsverzeichnis ab etwa zwei Bildschirmen oder fünf Abschnitten.

Akzeptanzkriterium: Ein Leser kann die Aufgabe, die das Dokument beschreibt, nur mit dem Dokument erledigen.

Was sich zwischen den Zielen unterscheiden muss

Entscheidung	--target=human	--target=agent
Kritische Einschränkungen	einmal, auf dem ersten Bildschirm, markiert	einmal oben unter ~100 Zeilen; zuerst und identisch wiederholt am Ende darüber hinaus
Abschnittsunabhängigkeit	Abschnitte können auf frühere aufbauen	jeder Abschnitt in sich abgeschlossen
Querverweise	"siehe oben" ist in Ordnung	nenne die genaue Überschrift
Überschriften	beschreibend und lesbar	eindeutig, wörtlich, grep-gerecht
Verbote	"mache X nicht" ist in Ordnung	"mache Y" trägt das Verbot
Bezeichner	einmal einführen, dann verkürzen	jedes Mal vollständig und wörtlich
Begründungen	Prosa behält die kausalen Verbindungen	behalte nur, wo sie eine Handlung ändert
Inhaltsverzeichnis	ab ~2 Bildschirmen	ab ~100 Zeilen
Länge	etwa die Hälfte der ursprünglichen Wörter	kürzeste Form, die jede Tatsache bewahrt

Abweichungsprüfung – ERFORDERLICH. Nenne vor dem Schreiben der Datei mindestens drei Entscheidungen, die dieser Lauf aufgrund des erklärten Ziels anders getroffen hat, und füge sie in den Bericht ein.