dx-roaster
Roasted ein GitHub-Repo in Sachen Developer Experience. Erzeugt vier Dateien: roast.md, action-plan.md, ideal-readme.md, score.json. Entwickelt für OSS-Maintainer und Dev-Tool-Gründer, die sich auf Show HN, Product Hunt oder einen Launch vorbereiten, bei dem die ersten fünf Minuten entscheidend sind.
Wichtige Regeln (vor jedem Durchlauf lesen)
-
Lies alle drei Referenzdateien VOR der Bewertung.
references/scoring-rubric.md,references/roast-voice-guide.md,references/readme-template.md. Die Rubrik ist nicht verhandelbar – verwende die exakten 10 Dimensionen. -
Bewerte jede Dimension auf der Skala 0–10. Niemals überspringen. Fehlende Daten = Punktzahl 0, nicht „N/A".
-
Der Roast muss konkrete Fundstellen zitieren. Zitiere schlechte Zeilen wörtlich. Referenziere Dateipfade. Nenne Zeilennummern, wenn möglich. Schreibe niemals allgemeine Floskeln wie „die Dokumentation könnte besser sein".
-
Der Ton ist wichtig. Standard ist
honest. Wechsle die Stimme gemäßreferences/roast-voice-guide.md. Brutal ist lustig, aber niemals persönlich. Freundlich ist ermutigend, aber dennoch konkret. -
Der Aktionsplan ist nach Impact sortiert, nicht nach Schweregrad. Verwende
impact × (1 / effort). Ein 5-Minuten-Fix, der 10 Punkte bringt, steht über einem 2-Stunden-Fix, der 12 Punkte bringt. -
Erfinde niemals URLs. Schreibe in
ideal-readme.mdfehlende Links mit<placeholder>-Syntax. Der Roast sagt dem Maintainer, dass er sie ausfüllen soll. -
Nenne niemals Maintainer oder Beitragende. Roaste die Arbeit, nicht die Personen.
-
Gib genau vier Dateien aus in
dx-roast/. Schreibe nicht an andere Orte. Überspringe keine Dateien.
Schritt 1: Annahme
Erforderlich:
repo– lokaler Pfad (Standard.) ODERhttps://github.com/owner/repo-URL
Optional:
| Parameter | Standard | Beschreibung |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | Wohin die 4 Ausgabedateien geschrieben werden |
compare_to | keiner | Optionale zweite Repo-URL für Benchmark-Vergleich |
Falls repo eine URL ist: Klone in ein temporäres Verzeichnis mit git clone <url> /tmp/dx-roast-<short-hash>. Scanne von dort. Lösche das temporäre Verzeichnis nach dem Durchlauf.
Falls repo . oder ein lokaler Pfad ist: Scanne direkt vor Ort, verändere nichts.
Schritt 2: Erkunden
Lies diese Dateien (jede kann fehlen – notiere das Fehlen):
README.md– vollständiger Inhalt, Struktur (Überschriften), Codeblöcke, Bildreferenzen, Badge-URLsCONTRIBUTING.md,CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/,.github/PULL_REQUEST_TEMPLATE.md,.github/CODEOWNERSpackage.json(Beschreibung, Homepage, Repository, Lizenz, Skripte),pyproject.toml,Cargo.toml,go.modLICENSE(Existenz + Typ)docs/-Ordner-Inhalt (nur Dateinamen + Größen)examples/odersamples/odercookbook/-Ordner.github/workflows/*.yml(nur Namen + kurze CI-Prüfung)
Falls repo eine URL ist, rufe zusätzlich via gh ab:
g-h api repos/<owner>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
gh api repos/<owner>/<repo>/commits --jq '.[0].commit.author.date' | head -1
gh api repos/<owner>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
Fange Fehler ab und fahre fort, falls ein GitHub-Aufruf fehlschlägt.
Schritt 3: 10 Dimensionen bewerten
Gib für jede der 10 Dimensionen in references/scoring-rubric.md aus: {score: 0–10, evidence: [...]} wobei evidence eine Liste mit 1–3 kurzen Zeichenketten ist, die deine Funde zitieren.
Beispiel:
"visual_proof": {
"score": 4,
"evidence": [
"1 Screenshot gefunden in Zeile 89 (unter der Falz)",
"Keine animierte Demo / kein GIF",
"Kein Video"
]
}
Summiere die Punktzahlen → Gesamtpunktzahl (0–100) → Note (A/B/C/D/F gemäß Rubrik).
Speichere in dx-roast/score.json mit genau dieser Struktur:
{
"repo": "<owner/repo or local path>",
"scanned_at": "<ISO 8601 timestamp>",
"dimensions": {
"time_to_first_success": { "score": 7, "evidence": ["..."] },
"what_is_this_clarity": { "score": 5, "evidence": ["..."] },
"visual_proof": { "score": 4, "evidence": ["..."] },
"install_simplicity": { "score": 9, "evidence": ["..."] },
"runnable_quick_start": { "score": 8, "evidence": ["..."] },
"documentation_depth": { "score": 6, "evidence": ["..."] },
"examples": { "score": 5, "evidence": ["..."] },
"community_signals": { "score": 3, "evidence": ["..."] },
"trust_signals": { "score": 7, "evidence": ["..."] },
"marketing_signals": { "score": 4, "evidence": ["..."] }
},
"total": 58,
"grade": "D",
"tone": "honest"
}
Schritt 4: Den Roast schreiben
Lies references/roast-voice-guide.md. Wende den gewünschten Ton an. Schreibe 250–500 Wörter in dx-roast/roast.md.
Erforderliche Struktur:
# DX Roast: <Repo-Name>
**Note: <Buchstabe> (<Gesamtpunktzahl>/100)** · Ton: <Ton>
<Absatz 1: das Urteil. Was funktioniert + die große Lücke.>
<Absatz 2: zitiere 2 konkrete Funde mit Dateireferenzen.>
<Absatz 3: zitiere 2 weitere Funde, verknüpft mit Dimensionspunktezahlen.>
<Absatz 4 (optional): eine letzte Wendung oder ein Vergleich mit einem bekannten guten Repo.>
<Schlussabsatz: verweise auf `action-plan.md` für den weiteren Weg.>
Jeder Roast muss mindestens 3 konkrete Funde aus den Evidence-Arrays von score.json referenzieren.
Schritt 5: Aktionsplan erstellen
Berechne priority = impact / effort_minutes für jeden Kandidaten-Fix. Nimm die Top 5–10. Sortiere absteigend nach Priorität.
Schreibe für jeden Fix in dx-roast/action-plan.md:
### N. <Fix im Imperativ, eine Zeile>
**Warum:** <Ein-Satz-Begründung. Referenziere die verbesserte Dimension.>
**Impact:** +<X> Punkte · **Aufwand:** <5min / 30min / 2h / half-day>
**So geht's:**
1. <Konkreter Schritt 1>
2. <Konkreter Schritt 2>
3. <Konkreter Schritt 3>
<Optionaler Code-/Markdown-Ausschnitt, der die exakte Änderung zeigt>
Eröffne action-plan.md mit:
# Aktionsplan — <Repo-Name>
Aktuelle Note: <Buchstabe> (<Gesamtpunktzahl>/100)
Top-Fixes, sortiert nach Impact × Aufwand. Führe sie in dieser Reihenfolge aus.
---
Schritt 6: Ideales README erstellen
Lies references/readme-template.md. Fülle die Vorlage gemäß dem Abschnitt „Ausfüllregeln". Schreibe in dx-roast/ideal-readme.md.
Verwende Platzhalter <homepage_url> usw. für fehlende Werte. Längenbegrenzung: 100 Zeilen.
Schritt 7: Terminal-Zusammenfassung
Gib dem Benutzer dieses exakte Format aus:
DX Roast abgeschlossen — Note: <Buchstabe> (<Gesamtpunktzahl>/100)
Top 3 Fixes (nach Impact sortiert):
1. <Fix 1> +<X> Pkt. · <Aufwand>
2. <Fix 2> +<X> Pkt. · <Aufwand>
3. <Fix 3> +<X> Pkt. · <Aufwand>
Dateien:
→ dx-roast/roast.md (teilbares Urteil)
→ dx-roast/action-plan.md (priorisierte Fixes)
→ dx-roast/ideal-readme.md (Zielzustand)
→ dx-roast/score.json (Rohpunkte)
Falls compare_to angegeben wurde, füge eine Vergleichszeile hinzu:
Benchmark: <anderes Repo> erzielt <X>/100 (Note <Y>) — Differenz von <Delta> Punkten.
Selbst-QA (jeder Durchlauf, vor dem Ausgeben der Terminal-Zusammenfassung)
- Alle 10 Dimensionen in
score.jsonhaben Punktzahl + Belege - Gesamtpunktzahl entspricht der Summe der Dimensionen
- Notenbuchstabe entspricht der Gesamtpunktzahl gemäß Rubrik-Schwellenwerten
- Roast referenziert mindestens 3 Belegpunkte aus score.json
- Roast nennt keinen Maintainer / Beitragenden
- Aktionsplan enthält 5–10 Einträge, absteigend nach Priorität sortiert
- Ideales README hat weniger als 100 Zeilen
- Ideales README verwendet
<placeholder>für jede nicht gefundene URL - Alle 4 Dateien existieren in output_dir
- Keine
<TBD>/<TODO>-Platzhalter in roast.md oder action-plan.md
Falls eine Prüfung fehlschlägt, korrigiere und führe den Schritt erneut aus.
Fehlerbehandlung
Diese vier Fehlerfälle werden explizit behandelt – lasse das Skill niemals stillschweigend eine teilweise Ausgabe produzieren, ohne die Ursache zu nennen.
| Fall | Verhalten |
|---|---|
repo existiert nicht ODER kann nicht geklont werden ODER kann nicht gelesen werden | Sofort beenden mit der Meldung Repo nicht gefunden oder nicht zugänglich: <repo>. Keine Ausgabedateien schreiben. |
README.md fehlt | Trotzdem ausführen. Bewerte what_is_this_clarity, visual_proof, runnable_quick_start und marketing_signals nahe 0. Nutze die Abwesenheit als Einstieg in den Roast („Kein README ist eine Aussage für sich"). |
| Repo ist privat + keine GitHub-Authentifizierung verfügbar | Versuche einen lokalen Clone (git clone <url>); falls fehlgeschlagen, beende mit Repo ist privat und keine Authentifizierung verfügbar. Schlage vor, dass der Benutzer GITHUB_TOKEN setzt oder einen lokalen Pfad übergibt. |
compare_to-URL schlägt fehl (Netzwerk, 404, privat, usw.) | Ohne Benchmark fortfahren. Füge dem Roast eine einzelne Zeile hinzu: Hinweis: Der angeforderte Benchmark gegen <compare_to> konnte nicht abgerufen werden. Lasse die Zeile Benchmark: aus der Terminal-Zusammenfassung weg. |
Jeder GitHub-API-Fehler (Ratenlimit, vorübergehender 5xx) während des Metadatenabrufs in Schritt 2 wird abgefangen und in score.json unter trust_signals.evidence als "github-metadaten nicht verfügbar" protokolliert. Der Rest des Durchlaufs wird fortgesetzt.
Beispiele
Gute Aufforderung:
„Roaste mein Repo unter https://github.com/myorg/mytool – Ton: brutal."
→ Skill klont, scannt, bewertet, schreibt 4 Dateien nach dx-roast/, gibt Zusammenfassung aus. Gesamte Laufzeit <60s für ein typisches Repo.
Guter Vergleich:
„DX-Audit für das aktuelle Verzeichnis. Benchmark gegen https://github.com/vercel/next.js."
→ Scannt beide, bewertet das aktuelle, fügt Benchmark-Zeile in Roast und Zusammenfassung ein.
Was dieses Skill NICHT tut
- Es verändert das Ziel-Repo nicht (schreibgeschützter Scan)
- Es führt keine Sicherheitsaudits oder Abhängigkeitsscans durch
- Es erstellt keine Marketingtexte (Aktionspunkte sind konkret, nicht „für den Ton umschreiben")
- Es erzeugt keine Bilder oder Assets (nur Platzhalter)
- Es postet nicht in sozialen Medien (schreibt nur teilbaren Text)