0x0w1/jig

README

Verwende diesen Skill, um die README.md eines Repositorys aus dem tatsächlichen Repository-Zustand zu erstellen oder zu aktualisieren.

Vorgehen

1. Scanne das Repository:
   • Manifest- und Build-Dateien: pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, Sperrdateien.
   • Einstiegspunkte, CLI-Argument-Definitionen, Skripte und Service-Konfigurationen (Dockerfile, docker-compose*.yml).
   • Vorhandene Dokumentation unter docs/ und Nutzungsbeispiele im Code.
2. Klassifiziere den Projekttyp: CLI-Tool, Bibliothek, Dienst/App oder Sonstiges. Der Typ wählt das unten stehende Abschnittslayout, wenn kein Profil gesetzt ist.
3. Lege das README-Profil gemäß dem Profilvertrag unten fest. Ein aufgelöstes Profil ersetzt die generischen Standardwerte für dieses Repository; wenn keins aufgelöst wird, schlage eines vor und fahre auf beide Arten fort.
4. Verzweige je nach aktuellem Zustand:
   • Keine README.md → Erstellungspfad: Entwurf der README mit dem unten stehenden Abschnittslayout.
   • README.md existiert → Aktualisierungspfad: Überprüfe jede überprüfbare Behauptung in der README – Befehle, Optionen, Dateipfade, Links, Feature-Aussagen – gegen das Repository. Sammle Abweichungen in einer Abweichungsliste, melde die Liste und wende dann die Korrekturen an. Lasse Abschnitte, die noch korrekt sind, unberührt.
5. Wende die Genauigkeitsregeln auf jede geschriebene Zeile an.
6. Führe den Komprimierungspass gemäß den Komprimierungsregeln unten aus:
   • Erstellungspfad: Wende ihn während des Entwurfs an. Es wurde noch nichts veröffentlicht, also gibt es nichts vorzuschlagen.
   • Aktualisierungspfad: Sammle Duplikate und Übertreibungen in einem Vorschlag – benenne jede Tatsache, wo sie wiederholt wird und welches Detail-Dokument sie enthalten würde – frage dann, bevor du etwas verschiebst. Melde den Vorschlag, auch wenn der Benutzer ihn ablehnt.
7. Führe die Änderung zusammen:
   • Wenn das Repository den Skill develop-task-flow (oder den installierten jig-develop-task-flow) besitzt, folge ihm: ein chore/<slug>-Branch, ein Squash-Merge mit einem docs:-Commit, dann Push auf develop.
   • Andernfalls schlage einen normalen Commit auf dem aktuellen Branch vor.

Profilvertrag

Zwei Repositorys desselben Projekttpps schreiben ihre READMEs trotzdem unterschiedlich: Eines unterhält eine übersetzte Spiegelung, ein anderes verschiebt die Installation in eine Anleitung, ein drittes hat eine Tabellenkonvention, die seine Mitwirkenden bereits befolgen. Das sind Entscheidungen, keine Fakten, die das Repository gescannt werden können, also werden sie einmal aufgezeichnet und bei jedem späteren Durchlauf gelesen.

Löse das Profil in dieser Reihenfolge auf:

1. JIG_README_PROFILE-Umgebungsvariable.
2. git config --local --get jig.readmeProfile.
3. .jig/readme.md.

Wenn ein Profil aufgelöst wird, überschreibt es die Abschnittsanordnung und Sprachregeln unten für dieses Repository; alles, was es nicht erwähnt, fällt auf diese zurück. Lese es, befolge es und nenne es im Bericht.

Wenn keins aufgelöst wird, erstelle eines aus dem Scan und schlage es vor: den klassifizierten Typ, die Sprache, in der das Repository bereits schreibt, ob eine Spiegelung existiert, die Abschnittsreihenfolge, die die aktuelle README impliziert, und welche Detail-Dokumente bereits Überlauf enthalten. Schreibe .jig/readme.md erst, nachdem der Benutzer es akzeptiert hat. Wenn der Benutzer ablehnt oder nicht antwortet, fahre mit den generischen Standardwerten fort und sage dies – ein fehlendes Profil ist ein normaler Zustand, kein Hindernis.

Die Datei zeichnet nur Entscheidungen auf. Sie enthält keine Schwellenwerte und keine Checkliste; die README-Qualität bleibt ein Urteil, das dieser Skill mit dem Repository vor sich trifft.

# README-Profil

> Grundlage: <wie dies entschieden wurde>, <YYYY-MM-DD>

## Sprachen

Kanonisch: `README.md` (Englisch). Spiegelung: `README.ko.md` (Koreanisch), aktualisiert im selben Task.

## Abschnitte

Titel- und Link-Zeile, Was das ist, Schnellstart, Skills, Dokumentation, Lizenz.

## Detail-Dokumente

Installationsoptionen → `docs/installation.md`. Roadmap und Design-Aufzeichnungen → `docs/roadmap.md`, nur von der Dokumentationsstartseite verlinkt.

## Konventionen

Identifikatortabellen behalten Beschreibungszellen auf einem Satz. Mitwirkenden-Befehle bleiben in einem `<details>`-Block.

Abschnittstitel sind der Vertrag; der Text darunter ist der des Repositorys. Ein Profil, das vor diesen Titeln geschrieben wurde, liest sich immer noch korrekt, wenn es sie verwendet.

Abschnittsanordnung

Erforderliche Abschnitte in dieser Reihenfolge:

1. Titel plus einzeilige Beschreibung.
2. Einführung: Was das Projekt tut und warum es existiert.
3. Installation.
4. Nutzung.

Ergänzungen nach Projekttyp:

• CLI-Tool: eine Befehls- und Optionstabelle.
• Bibliothek: eine API-Zusammenfassung mit Beispielcode.
• Dienst/App: wie man es ausführt (Entwicklung und Produktion) und die erforderlichen Umgebungsvariablen.

Optional: Dokumentationslinks, Lizenz.

Anordnungsregeln

• Eine Tabelle ist für Identifikatoren geeignet, die Leute kopieren – Skill-Namen, Befehle, Optionen, Pfade. Was einen solchen Namen beschädigt, ist das Breitenverhältnis zwischen den Spalten: GitHub dimensioniert Spalten nach Inhalt, sodass eine Beschreibungsspalte, die mehrmals länger als die Identifikatorspalte ist, den Identifikator zusammendrückt, bis er mitten im Namen umbricht, und der Leser einen Namen sieht, der nicht existiert.
• Halte Beschreibungszellen etwa so kurz wie die Identifikatoren, etwa ein Satz. Wenn Beschreibungen lang werden, kürze sie oder verschiebe das Ganze in eine Liste: - **name** — Beschreibung.
• Umbruch innerhalb einer Beschreibung ist zu erwarten und erfordert keine Bearbeitung.

Komprimierungsregeln

Eine README wird gelesen, bevor der Leser sich entschieden hat, das Projekt zu verwenden. Alles darin konkurriert um diese Aufmerksamkeit, also ist Länge ein Symptom: Eine lange README ist fast immer eine Tatsache, die an mehreren Stellen geschrieben wurde, kein Projekt mit viel zu sagen.

Verschieben, nicht löschen. Wenn dieselbe Tatsache an mehr als einer Stelle erscheint, behalte sie an der Stelle, an der ein Leser zuerst ankommt, und verschiebe den Rest in das Detail-Dokument, das sie bereits abdeckt, erstelle dieses Dokument nur, wenn keins existiert. Nichts geht verloren; die README hört auf, sich zu wiederholen. Es gibt keine Zeilenanzahl, die erreicht werden muss – eine Bibliotheks-README mit den API-Beispielen, die sie wirklich braucht, ist nicht zu lang, und eine kurze README, die dasselbe zweimal sagt, ist immer noch falsch.

Führe mit dem, was der Leser bekommt. Die Einführung sagt, was einfacher wird, nicht, welche Funktionen existieren. zeichnet einen bewerteten Release-Trailer beim Merge auf ist eine Funktion; du hörst auf zu rekonstruieren, warum eine Version ein Minor war ist das, was der Leser bekommt. Ordne die Behauptungen nach der Stärke der Evidenz, die stärkste zuerst, und lasse jede umgebende Prosa sie in derselben Reihenfolge auflisten – ein Absatz und seine Aufzählungspunkte dürfen keine unterschiedlichen Prioritäten implizieren.

Behaupte nur, was das Repository belegen kann, und sage, wann es zutrifft. Eine Behauptung, die das Repository nicht demonstrieren kann, wird weggelassen, nicht abgeschwächt. Gib die Bedingung an, unter der der Wert erscheint, sodass ein Leser außerhalb dieser Bedingung das Projekt schnell ausschließen kann, anstatt es später zu entdecken.

Streiche, was nicht vor der Installation gelesen wird. Roadmaps, Design-Aufzeichnungen und Richtungsnotizen sind Dinge, die das Projekt für sich behält. Verlinke sie von der Dokumentationsstartseite, nicht von der README.

Falte Mitwirkenden-Material ein. Build-, Regenerierungs- und Validierungsbefehle dienen Leuten, die das Repository bereits geklont haben. Setze sie in einen <details>-Block oder ein Mitwirkenden-Dokument.

Führe Blöcke zusammen, die sich durch einen Wert unterscheiden. Separate Befehlsblöcke pro Plattform oder Ziel, die sich nur in einem Argument unterscheiden, werden zu einem Block mit benanntem Argument.

Gib dem Leser einen Weg über die Spitze hinaus. Wenn die README mehr als etwa vier Abschnitte hat, setze eine einzeilige Link-Zeile unter den Titel, damit ein wiederkehrender Leser direkt zu dem Abschnitt springen kann, für den er gekommen ist.

Genauigkeitsregeln

• Schreibe nur Installations- und Ausführungsbefehle, die gegen das Repository verifiziert wurden: Ein Skript, Manifest oder eine Sperrdatei muss sie zeigen.
• Überprüfe, dass jeder verlinkte Dateipfad existiert.
• Beschreibe keine Funktionen, Badges oder Integrationen, die das Repository nicht enthält.
• Wenn eine Behauptung nicht verifiziert werden kann, lass sie weg und melde sie stattdessen.

Sicherheitsregeln

• .jig/readme.md wird nur geschrieben, nachdem der Benutzer den Vorschlag akzeptiert hat, und niemals als Nebeneffekt einer gewöhnlichen README-Aktualisierung.
• Eine vorhandene .jig/readme.md wird niemals ohne explizite Bestätigung überschrieben. Schlage die Änderung vor und nenne, was sie ersetzt.
• Nichts anderes unter .jig/ wird berührt. version-rubric besitzt .jig/versioning.md.
• Eine veröffentlichte README wird niemals stillschweigend umstrukturiert; der Komprimierungspass schlägt vor und wartet.
• Nicht zusammenhängende Benutzeränderungen werden beibehalten.

Sprachregeln

• Eine vorhandene README behält ihre Sprache.
• Eine neue README wird in der Sprache geschrieben, die das Repository bereits für seine Dokumente verwendet, standardmäßig Englisch, mit technischen Begriffen in Backticks.
• Eine explizite Sprachaufforderung des Benutzers überschreibt beides.

Bericht

• Projekttyp und eingeschlagener Pfad (Erstellung oder Aktualisierung).
• README-Profil: Pfad und Quelle, oder vorgeschlagen und abgelehnt, oder keins und mit generischen Standardwerten laufend.
• Im Aktualisierungspfad: die Abweichungsliste und was korrigiert wurde.
• Der Komprimierungsvorschlag: jede Tatsache, die an mehr als einer Stelle wiederholt wurde, wohin sie verschoben werden würde und ob der Benutzer sie akzeptiert hat.
• Behauptungen, die nicht verifiziert werden konnten und weggelassen wurden.