Communitygithub.com

T0mSIlver/skills

Entfernt selbstreferenzielle Metakommentare – Texte, die das Artefakt beschreiben, das sie umgibt, das wiederholen, was der Leser bereits sieht, oder den Prozess ihrer Entstehung nacherzählen – aus UI-Texten, Dokumentationen, Code-Kommentaren, Commit-Nachrichten und PR-Beschreibungen. Anwenden beim Schreiben oder Überprüfen dieser Oberflächen und vor dem Entschlacken bei der Bearbeitung von Prosa.

Was ist skills?

Dieses Skill, `Unnarrate`, ist ein Begleiter zum `unslop`-Skill. Es identifiziert und entfernt automatisch Meta-Kommentare aus verschiedenen Entwickleroberflächen – UI-Kopien, Dokumentationen, Code-Kommentaren, Commit-Nachrichten und PR-Beschreibungen. Meta-Kommentare sind Texte, die das Artefakt beschreiben, das sie umgibt, etwas wiederholen, was der Leser bereits sieht (wie ein Tooltip, der die Beschriftung wiederholt), oder den Prozess nacherzählen, der sie erzeugt hat (z. B. „Wie gewünscht in einen Helfer extrahiert“). Das Skill bietet einen Löschtest: Wenn ein Satz nach gedanklichem Entfernen keinen Verlust bedeutet oder auf jedes andere Projekt gleichermaßen zuträfe, sollte er gelöscht werden. Es behandelt spezifische Muster für jede Oberfläche, warn't jedoch auch vor dem Beibehalten wichtiger Kommentare wie solche, die Rationale, Invarianten oder Warnungen enthalten. Das Skill kann mit Cursor, Claude Code, Codex, Copilot-Chat und anderen KI-gestützten Entwicklungsumgebungen arbeiten, die Skills unterstützen, und erfordert keine Installation – es wird in das Agenten-Prompt eingefügt.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/T0mSIlver/skills/tree/HEAD/unnarrate

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Unnarrate

Begleiter zu unslop. Unslop korrigiert, wie KI-Prosa klingt; dieses Skill löscht Text, der gar nicht existieren sollte: Metakommentare – Texte, die das Artefakt für sein eigenes Publikum nacherzählen. Ein Fortschrittsbalken kündigt bereits Fortschritt an; „Fortschritt wird während des Laufs angezeigt“ daneben ist ein zweites, redundantes Zeichen. Agenten produzieren dies ständig, weil sie ihren Gedankengang auf jede Oberfläche projizieren, die sie berühren.

Der Löschtest

Lösche jeden Satz, jede Bezeichnung oder jeden Kommentar, dessen einziger Inhalt ist:

  1. Eine Beschreibung des Artefakts, in dem er sich befindet („Dieser Abschnitt beschreibt …“),
  2. Etwas, das der Leser bereits sehen kann (ein Tooltip, der die Bezeichnung wiederholt; ein Kommentar, der die nächste Zeile wiederholt), oder
  3. Der Prozess, der ihn hervorgebracht hat (// Wie gewünscht in einen Helfer extrahiert).

Zwei Prüfungen entscheiden über knifflige Fälle:

  • Lösche ihn gedanklich. Wenn der Leser nichts verliert, war es eine Null-Operation – Text, der etwas zu tun scheint, aber nichts ändert.
  • Portabilität. Wenn die Zeile unverändert in einem anderen Projekt, einem anderen PR oder über anderem Code stehen könnte, sagt sie nichts über dieses hier aus. Entferne sie.

Was zu löschen ist, nach Oberfläche

UI-Texte

  • Texte, die Verhalten beschreiben, das die Schnittstelle bereits ausführt: „Fortschritt wird während der Installation angezeigt“, „Ein Spinner erscheint beim Laden“, „Die Liste aktualisiert sich automatisch“. Das Widget ist das Zeichen; füge kein verbales hinzu.
  • „Ladevorgang …“-Text neben einem sichtbaren Spinner; „Datei erfolgreich hochgeladen“ → „Datei hochgeladen“.
  • Tooltips und Hilfetexte, die die Bezeichnung wiederholen: Feld „Geburtsstadt“, Hinweis „Geben Sie Ihre Geburtsstadt ein“.
  • Positionsbeschreibungen: „Klicken Sie unten auf die Schaltfläche zum Absenden“, „Wählen Sie eine Option aus dem Dropdown-Menü“.
  • Onboarding-/Coach-Mark-Texte, die jedes Steuerelement auflisten, anstatt auf die eine nicht offensichtliche Aktion zu verweisen.
  • Zugänglichkeitsduplikate: aria-label="Schaltfläche zum Absenden" auf einem <button>, alt="Bild eines Diagramms" (Bildschirmlesegeräte kündigen die Rolle bereits an).

Dokumentationen und READMEs

  • „Dieses Dokument beschreibt …“, „In diesem Leitfaden werden wir …“, „Willkommen zur Dokumentation von X“. Beginne mit dem Inhalt.
  • Übersichtsabschnitte, die nur die folgenden Abschnitte ankündigen; abschließende „Zusammenfassung“-Absätze, die die Seite wiederholen.
  • Docstrings, die die Signatur wiederholen (get_user(id) – „Ruft den Benutzer anhand der ID ab“); <summary>Ruft X ab oder legt X fest</summary>. PEP 257 verbietet genau das.
  • „Das folgende Beispiel zeigt, wie …“ über einem Beispiel; Prosa, die den benachbarten Codeblock wiederholt.
  • Funktionspunkte und Abschnittseinleitungen, die für jedes Projekt zutreffen würden.

Codekommentare

  • Wiederholung der nächsten Zeile: // Importiere React, // Gib den Wert zurück, // Iteriere über Elemente.
  • Abschnittsbanner: // ===== HELFER =====, // --- Schritt 3: Validieren ---.
  • Plan- und Phasenbeschreibungen: // Phase 2: Refactoring, // Verwendung des neu erstellten Foo-Modells.
  • Änderungsprotokolle: // Wechsel von useState zu useReducer, // Alten Handler entfernt. Die Git-Historie enthält dies.
  • Kommentare, die an den Prüfer gerichtet sind, nicht an den zukünftigen Leser: // Hinweis: Ich habe dieses Verhalten intakt gelassen.

Commits und PRs

  • Aufzählungen, die das Diff Datei für Datei wiederholen; „Dieser PR fügt … hinzu“ gefolgt vom Titel wörtlich.
  • Vorlagenabschnitte, die mit Wiederholungen gefüllt sind; „Testplan: Tests durchgeführt“ ohne konkrete Angaben.
  • Aufwandsbeschreibungen: „Umfassendes Refactoring“, „Rückwärtskompatibilität sorgfältig bewahrt“. Nenne Fakten, die ein Prüfer überprüfen kann.

Behalten – nicht alles, was nacherzählt, ist eine Null-Operation

  • Live-Erzählung ist ein Zeichen; statische Erzählung ist das Problem. Ein Agent, der während der Arbeit „Installiere Abhängigkeiten …“ streamt, ist echtes Feedback. Text, der beschreibt, dass dieses Feedback existiert, ist das Anti-Muster.
  • „Warum“-Kommentare bleiben: Begründungen, Invarianten, Warnungen vor nicht offensichtlichem Verhalten, Verweise auf Probleme und Vorfälle. Die Regel löscht Wiederholungen, nicht Kommentare – passe die Kommentardichte des umgebenden Codes an.
  • Anweisungen, die Informationen enthalten, die die Oberfläche nicht zeigen kann, bleiben: Formate („JJJJ-MM-TT“), Einschränkungen („8+ Zeichen“), Nebenwirkungen („dies sendet eine E-Mail an das Team“), Warnungen vor Unumkehrbarkeit.
  • Echter Alt-Text bleibt. Lösche das „Bild von …“-Präfix, behalte die Beschreibung dessen, was das Bild zeigt.
  • TODOs mit einem Tracking-Link bleiben; bloßes // TODO: verbessern wird entfernt.

Anwendung

  1. Durchsuche die geänderten Oberflächen nach den obigen Mustern. Lösche, schreibe nicht um – die meisten Treffer benötigen keinen Ersatz.
  2. Wenn das Löschen eine echte Lücke hinterlässt, repariere das Artefakt (klarere Bezeichnung, selbsterklärendes Steuerelement), nicht die Erzählung.
  3. Führe dann unslop auf dem, was übrig bleibt, aus.

reference/terminology.md benennt das Phänomen pro Community (Metadiskurs, Happy Talk, offensichtliche Kommentare, Null-Operationen) mit Quellen, um die Checkliste zu zitieren oder zu erweitern.

Verwandte Skills