| name | user-changelog-german |
| description | Use when creating a human-readable German changelog for non-technical end users of berliner-schnauze.wtf from a GitHub PR or version entry in CHANGELOG.md. Triggers on requests like "schreib einen User-Changelog", "menschenlesbarer Changelog", "Changelog für meine User", or any changelog task targeting non-developers. Supports args: a version number, "latest", "aufholen" (generate all missing changelogs), "update" (re-apply current schema to existing files). |
User-Changelog auf Deutsch (Non-Technical)
Zweck
Technische Commit-Listen aus CHANGELOG.md oder GitHub-PRs in verständliche, nutzerorientierte Release-Notes auf Deutsch übersetzen — für Menschen, die nicht programmieren.
Argumente
Der Skill nimmt ein optionales Argument, das den Modus bestimmt:
| Argument | Verhalten |
|---|
(leer) oder latest | Changelog für die neueste Version in CHANGELOG.md schreiben |
x.y.z (z. B. 3.41.0) | Changelog für genau diese Version schreiben |
aufholen | Alle fehlenden Changelogs nachziehen (siehe unten) |
update | Bestehende Changelog-Dateien ans aktuelle Schema anpassen (siehe unten) |
Modus aufholen
Lücken schließen: Versionen in CHANGELOG.md mit vorhandenen Dateien in docs/user-changelog/ abgleichen.
- Alle Versionsnummern aus CHANGELOG.md extrahieren (
# [x.y.z]-Überschriften)
- Mit
docs/user-changelog/v*.md vergleichen — fehlende Versionen ermitteln
- Für jede fehlende Version einen Changelog schreiben, chronologisch von alt nach neu — so bauen Titel-Variation und Themenbezüge sinnvoll aufeinander auf
- Versionen, bei denen nach dem Clustering nichts Nutzersichtbares übrig bleibt (z. B. reine Patch-Releases mit CI-/Build-Fixes), überspringen und am Ende auflisten — eine leere Seite mit nur "Verbesserungen im Hintergrund" bringt niemandem was
- Am Ende zusammenfassen: welche Dateien erstellt, welche Versionen übersprungen und warum
Modus update
Für den Fall, dass sich das Schema geändert hat (Frontmatter-Felder, Titel-Regeln, Formatvorgaben): bestehende Dateien in docs/user-changelog/ ans aktuelle Format anpassen — ohne den redaktionellen Inhalt neu zu schreiben.
- Jede Datei in
docs/user-changelog/ gegen das aktuelle Ausgabeformat, die Titel-Regeln und die Qualitätsprüfung dieses Skills prüfen
- Nur reparieren, was vom Schema abweicht: fehlende/falsche Frontmatter-Felder, verbotene H1/Datum-Zeilen im Inhalt, Titel nach altem Muster
- Fließtext und Bullet-Inhalte unangetastet lassen — die wurden bewusst so geschrieben; beim Titel-Neuschreiben den Aufhänger aus dem vorhandenen Inhalt der Datei ableiten
- Am Ende pro Datei auflisten, was geändert wurde — und welche Dateien schon konform waren
Quellen
- GitHub PR lesen —
mcp__plugin_github_github__pull_request_read mit method: get für Titel, Beschreibung, Merge-Datum
- CHANGELOG.md lesen — den vollständigen Versionsabschnitt (
# [x.y.z] bis zur nächsten Überschrift) für alle Commits
Clustering — Commits gruppieren
Technische Scopes auf nutzersichtbare Themen abbilden:
| Technische Scopes | Nutzerfreundliche Gruppe |
|---|
game, bon | Spiel-Bereich (z. B. "Berliner oder Nicht") |
word-page, word-*, component | Wort-Detailseite |
toast | Hinweis-Meldungen |
pwa, sw | App-Verhalten / Updates |
a11y, seo, styles, build | "Verbesserungen im Hintergrund" |
dropdown, tooltip | Bedienelemente |
Commits ohne sichtbare Nutzerwirkung (test, ci, docs, fix: formatting) weglassen.
Ausgabeformat
Die Datei beginnt immer mit YAML-Frontmatter — diese Felder werden von der Astro Content Collection für die /changelog/{version}-Seite ausgelesen. H1-Heading und Datum-Zeile nicht in den Markdown-Inhalt schreiben — das Template rendert sie aus dem Frontmatter.
---
version: "x.y.z"
releaseDate: "YYYY-MM-DD"
title: "[Aufhänger aus dem Release-Schwerpunkt] (Version x.y.z)"
description: "[1 Satz Zusammenfassung — erscheint auf der Übersichtsseite /changelog]"
---
[1–2 Sätze Zusammenfassung des Update-Schwerpunkts]
---
## [Hauptthema 1]
[Fließtext: Was kann der Nutzer jetzt tun, was vorher nicht möglich war?]
- Bullet-Liste mit konkreten Vorteilen aus Nutzersicht
- Kein Fachjargon (kein "refactored", "hydration", "SSR")
---
## [Hauptthema 2]
...
---
## Verbesserungen im Hintergrund
- Kleinere Fehlerbehebungen und technische Optimierungen als einfache Liste
Frontmatter-Felder:
| Feld | Inhalt |
|---|
version | Versionsnummer als String, z. B. "3.35.0" (kein v-Prefix) |
releaseDate | ISO-Datum, z. B. "2026-06-27" |
title | Individueller Aufhänger pro Release — siehe Titel unten |
description | 1 kurzer Satz für die Übersichtsseite — keine technischen Details, Nutzersprache |
Titel
Kein festes Schema — die Übersichtsseite /changelog hat bereits die H1 "Was ist neu?", darunter wird jeder title gelistet. Wenn jeder Eintrag mit "Was ist neu in Version…" beginnt, liest sich die Liste wie ein kaputter Kopierer. Stattdessen:
- Aufhänger aus dem größten sichtbaren Feature des Releases — der Titel soll neugierig machen, was drin ist
- Versionsnummer immer enthalten — als Anker in der Übersichtsliste und im OG-Title beim Teilen. Position flexibel: vorne, hinten, in Klammern
- Kurz halten (~60 Zeichen) — der Titel ist auch
opengraphTitle
- Ton wie der Rest: locker, direkt, gern mit Berliner Schnauze — aber kein Clickbait
- Satzbau variieren gegenüber den letzten Einträgen (vorher in
docs/user-changelog/ nachschauen) — nicht drei Releases hintereinander dasselbe Muster
Beispiele:
feat-Schwerpunkt: Spenden-Seite + Footer-Umbau
→ "Spendieren jeht jetzt — Version 3.38.0"
feat-Schwerpunkt: Haptik + Animationen im BON-Spiel
→ "Version 3.35.0: Det Spiel vibriert jetzt richtig"
Nur kleine Fixes, kein großes Feature
→ "Feinschliff überall (Version 3.36.0)"
Sprache & Ton
- Ich-Form — Felix schreibt als Einzelentwickler: "Ich habe… gebaut", "Ich habe… eingebaut", "Ich habe… neu gemacht"
- Kein "Wir" — Felix ist allein der Entwickler
- Ton: locker, direkt, erfahren — kein Grundschul-Deutsch, kein trockener Feature-Listen-Stil. Schreiben wie ein Entwickler der einem Freund erzählt was er gebaut hat. Leichtes Denglish ist willkommen wenn es natürlich klingt: "swipen", "sharen", "Redesign", "buggy", "Stacking", "Sidebar", "Sections", "straight forward". Umgangssprache die jeder versteht: "hat mich genervt", "täuscht sich schnell", "ehrlich gesagt". Nicht übertreiben — es soll authentisch klingen, nicht wie forciertes Jugendsprech.
- Leser werden nicht direkt angesprochen ("du") — stattdessen unpersönlich: "lässt sich", "kann man", "gibt es", "geht"
- Datum niemals mit Zahl beginnen (
27. Juni… → Veröffentlicht am 27. Juni…) — sonst Markdown-Linter-Fehler (MD029)
- Technische Begriffe erklären, nicht ersetzen: "haptisches Feedback (Vibration)"
- Kein Entwicklerjargon: kein "commit", "refactor", "SSR", "hydration", "chunk"
- Emojis nur wenn explizit gewünscht
Humanizer-Pass (vor dem Speichern)
Jeden neu geschriebenen Entwurf (Modi latest, Versionsnummer, aufholen) vor dem Speichern einmal gezielt auf KI-Schreibmuster durchgehen. Warum: Die Release-Notes leben von der Ich-Erzähler-Authentizität — ein einziger generisch klingender Absatz kippt den ganzen Eintrag. Modus update ist ausgenommen, dort wird redaktioneller Inhalt nicht angefasst.
Diese Muster rausschreiben:
- Gedankenstriche (
— und –) komplett vermeiden — das zuverlässigste KI-Erkennungszeichen. Ersetzen durch Komma, Punkt (neuer Satz), Doppelpunkt oder Klammern. Vor dem Speichern per Suche prüfen: kein einziges —/– im fertigen Text, auch nicht im title.
- Wiederholte Sprach-Tics über Einträge hinweg. Vor dem Schreiben die letzten 2–3 Dateien in
docs/user-changelog/ überfliegen: Taucht eine Wendung ("ehrlich gesagt", "hat mich genervt", "war überfällig") dort schon auf, eine andere Formulierung wählen. Ein Mensch wiederholt sich mal, aber nicht mit derselben Phrase in jedem Release.
- Kein Warm-up-Satz nach der Überschrift. "Die Suche hat mehrere Verbesserungen bekommen:" unter "## Suche aufpoliert" sagt nichts — direkt mit dem Inhalt anfangen.
- Keine erzwungenen Dreierreihen. Zwei Punkte sind zwei Punkte, vier sind vier. Aufzählungen nicht auf drei glattbügeln.
- Fragmente zu echten Sätzen machen. Angehängte Strich-Fragmente ("Links reagieren schneller — kein Warten mehr") als vollständigen Satz mit Subjekt schreiben.
- Werbedeutsch dämpfen. "blitzschnell", "nahtlos", "spürbar verbessert" durch konkrete Aussagen ersetzen: Was genau passiert jetzt anders?
- Kein generisch-positiver Schlusssatz ("Viel Spaß beim Entdecken!"). Der letzte Punkt ist einfach der letzte Inhaltspunkt.
- Satzlängen mischen. Kurzer Satz. Dann einer, der sich Zeit nimmt und einen Nebengedanken mitnimmt. Gleichförmige mittellange Sätze wirken generiert.
Nicht wegbügeln (das ist Stimme, kein Muster): Denglish ("swipen", "sharen", "hovered"), Meinung und Genervtsein, Umgangston, unvollständige Sätze als bewusstes Stilmittel ("Gab's vorher nicht, war aber überfällig."). Im Zweifel klingt der Text lieber etwas ruppig als glattpoliert.
Speicherort
docs/user-changelog/v{VERSION}.md
Beispiel-Mapping
fix(bon): defer correct-answer toast one rAF to avoid mobile compositor flash
→ weglassen (kein sichtbarer Nutzereffekt)
feat(game): add haptic vibration feedback via useVibrate
→ "Haptisches Feedback (Vibration) auf Smartphones bei richtigen und falschen Antworten"
fix(sidebar): scroll active nav tab into view on mobile
→ "Verbesserungen im Hintergrund: Seitenleisten-Navigation auf mobilen Geräten verbessert"
Qualitätsprüfung vor dem Speichern
