dx-roaster
Rôtit l'expérience développeur d'un dépôt GitHub. Produit quatre fichiers : roast.md, action-plan.md, ideal-readme.md, score.json. Conçu pour les mainteneurs OSS et les fondateurs d'outils de développement qui se préparent pour Show HN, Product Hunt, ou tout lancement où les cinq premières minutes comptent.
Règles critiques (à lire avant chaque exécution)
-
Lisez les trois fichiers de référence AVANT de noter.
references/scoring-rubric.md,references/roast-voice-guide.md,references/readme-template.md. La grille d'évaluation est non négociable — utilisez les 10 dimensions exactes. -
Notez chaque dimension sur l'échelle 0-10. Ne sautez jamais. Données manquantes = score 0, pas « N/A ».
-
Le roast doit citer des constats précis. Citez les mauvaises lignes textuellement. Référencez les chemins de fichiers. Citez les numéros de ligne si possible. N'écrivez jamais de platitudes génériques comme « la documentation pourrait être meilleure ».
-
Le ton compte. Par défaut
honest. Changez de voix selonreferences/roast-voice-guide.md. Brutal est drôle mais jamais personnel. Gentil est encourageant mais toujours spécifique. -
Le plan d'action est classé par impact, pas par sévérité. Utilisez
impact × (1 / effort). Un correctif de 5 minutes qui ajoute 10 points se classe au-dessus d'un correctif de 2 heures qui ajoute 12 points. -
N'inventez jamais d'URL. Lorsque vous écrivez
ideal-readme.md, utilisez la syntaxe<placeholder>pour les liens manquants. Le roast indiquera au mainteneur de les remplir. -
Ne nommez jamais les mainteneurs ou contributeurs. Rôtissez le travail, pas les personnes.
-
Produisez exactement quatre fichiers dans
dx-roast/. N'écrivez pas à d'autres emplacements. Ne sautez pas de fichiers.
Étape 1 : Prise en charge
Requis :
repo— chemin local (par défaut.) OU URLhttps://github.com/proprietaire/repo
Optionnel :
| Paramètre | Défaut | Description |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | Où écrire les 4 fichiers de sortie |
compare_to | aucun | URL d'un second dépôt optionnel pour comparaison de référence |
Si repo est une URL : clonez dans un répertoire temporaire avec git clone <url> /tmp/dx-roast-<court-hash>. Analysez à partir de là. Supprimez le répertoire temporaire après l'exécution.
Si repo est . ou un chemin local : analysez sur place, ne modifiez rien.
Étape 2 : Découverte
Lisez ces fichiers (chacun peut être absent — notez l'absence) :
README.md— contenu complet, structure (titres), blocs de code, références d'images, URL de badgesCONTRIBUTING.md,CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/,.github/PULL_REQUEST_TEMPLATE.md,.github/CODEOWNERSpackage.json(description, page d'accueil, dépôt, licence, scripts),pyproject.toml,Cargo.toml,go.modLICENSE(existence + type)- Contenu du dossier
docs/(juste les noms de fichiers + tailles) - Dossier
examples/ousamples/oucookbook/ .github/workflows/*.yml(juste les noms + brève vérification de présence CI)
Si repo est une URL, récupérez aussi via gh :
gh api repos/<proprietaire>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
gh api repos/<proprietaire>/<repo>/commits --jq '.[0].commit.author.date' | head -1
gh api repos/<proprietaire>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
Attrapez et continuez si un appel GitHub échoue.
Étape 3 : Noter 10 dimensions
Pour chacune des 10 dimensions dans references/scoring-rubric.md, produisez {score: 0–10, evidence: [...]} où evidence est une liste de 1 à 3 courtes chaînes citant ce que vous avez trouvé.
Exemple :
"visual_proof": {
"score": 4,
"evidence": [
"1 capture d'écran trouvée à la ligne 89 (sous le pli)",
"Aucune démo animée / gif",
"Aucune vidéo"
]
}
Additionnez les scores → total (0–100) → note (A/B/C/D/F selon la grille).
Sauvegardez dans dx-roast/score.json avec cette forme exacte :
{
"repo": "<proprietaire/repo ou chemin local>",
"scanned_at": "<horodatage ISO 8601>",
"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"
}
Étape 4 : Écrire le roast
Lisez references/roast-voice-guide.md. Appliquez le ton demandé. Écrivez 250–500 mots dans dx-roast/roast.md.
Structure requise :
# DX Roast : <nom du dépôt>
**Note : <lettre> (<total>/100)** · Ton : <ton>
<Paragraphe 1 : le verdict. Ce qui fonctionne + le grand écart.>
<Paragraphe 2 : citez 2 constats précis avec références aux fichiers.>
<Paragraphe 3 : citez 2 autres constats, reliez aux scores des dimensions.>
<Paragraphe 4 (optionnel) : une touche finale ou comparaison avec un dépôt connu de qualité.>
<Paragraphe de clôture : renvoyez à `action-plan.md` pour la voie à suivre.>
Chaque roast doit référencer au moins 3 constats précis issus des tableaux de preuves de score.json.
Étape 5 : Générer le plan d'action
Calculez priority = impact / effort_minutes pour chaque correction candidate. Prenez les 5 à 10 meilleures. Triez par priorité décroissante.
Pour chaque correction, écrivez dans dx-roast/action-plan.md :
### N. <Correction à l'impératif, une ligne>
**Pourquoi :** <Justification en une phrase. Référencez la dimension améliorée.>
**Impact :** +<X> points · **Effort :** <5min / 30min / 2h / demi-journée>
**Comment :**
1. <Étape concrète 1>
2. <Étape concrète 2>
3. <Étape concrète 3>
<Extrait de code/markdown optionnel montrant le changement exact>
Ouvrez action-plan.md par :
# Plan d'action — <nom du dépôt>
Note actuelle : <lettre> (<total>/100)
Meilleures corrections classées par impact × effort. À faire dans l'ordre.
---
Étape 6 : Générer le README idéal
Lisez references/readme-template.md. Remplissez le template selon la section « Règles de remplissage ». Écrivez dans dx-roast/ideal-readme.md.
Utilisez des placeholders <homepage_url> etc. pour les valeurs manquantes. Limite de longueur : 100 lignes.
Étape 7 : Récapitulatif terminal
Affichez ce format exact à l'utilisateur :
DX Roast terminé — Note : <lettre> (<total>/100)
Top 3 corrections (classées par impact) :
1. <correction 1> +<X> pts · <effort>
2. <correction 2> +<X> pts · <effort>
3. <correction 3> +<X> pts · <effort>
Fichiers :
→ dx-roast/roast.md (verdict partageable)
→ dx-roast/action-plan.md (correctifs priorisés)
→ dx-roast/ideal-readme.md (état cible)
→ dx-roast/score.json (notes brutes)
Si compare_to a été fourni, ajoutez une ligne de comparaison :
Référence : <autre dépôt> a un score de <X>/100 (note <Y>) — écart de <delta> points.
Auto-QA (à chaque exécution, avant d'afficher le récapitulatif terminal)
- Les 10 dimensions dans
score.jsonont un score + des preuves - Le total est égal à la somme des dimensions
- La lettre de note correspond aux seuils de la grille pour le total
- Le roast référence au moins 3 éléments de preuve de
score.json - Le roast ne nomme aucun mainteneur / contributeur
- Le plan d'action contient 5 à 10 éléments, triés par priorité décroissante
- Le README idéal fait moins de 100 lignes
- Le README idéal utilise
<placeholder>pour toute URL non trouvée lors de l'analyse - Les 4 fichiers existent dans output_dir
- Aucun placeholder
<TBD>/<TODO>dans roast.md ou action-plan.md
Si une vérification échoue, corrigez et réexécutez cette étape.
Gestion des erreurs
Ces quatre modes d'échec sont explicitement gérés — ne laissez jamais la compétence produire silencieusement une sortie partielle sans en révéler la cause.
| Cas | Comportement |
|---|---|
repo n'existe pas OU ne peut pas être cloné OU ne peut pas être lu | Quittez immédiatement avec le message Dépôt introuvable ou inaccessible : <repo>. N'écrivez aucun fichier de sortie. |
README.md est manquant | Exécutez quand même. Notez what_is_this_clarity, visual_proof, runnable_quick_start et marketing_signals près de 0. Utilisez l'absence comme ouverture du roast (« Pas de README, c'est une déclaration en soi »). |
| Dépôt privé + aucune authentification GitHub disponible | Essayez un clone local (git clone <url>) ; s'il échoue, quittez avec Le dépôt est privé et aucune authentification n'est disponible. Suggérez à l'utilisateur de définir GITHUB_TOKEN ou de passer un chemin local. |
L'URL compare_to échoue (réseau, 404, privé, etc.) | Continuez sans la référence. Ajoutez une seule ligne au roast : Note : la référence demandée par rapport à <compare_to> n'a pas pu être récupérée. Omettrez la ligne Référence : du récapitulatif terminal. |
Toute erreur d'API GitHub (limite de débit, 5xx transitoire) lors de la récupération des métadonnées à l'étape 2 est capturée et enregistrée dans score.json sous trust_signals.evidence comme "métadonnées github indisponibles". Le reste de l'exécution se poursuit.
Exemples
Bonne invocation :
« Rôtis mon dépôt à l'adresse https://github.com/monorg/monoutil — ton : brutal. »
→ La compétence clone, analyse, note, écrit 4 fichiers dans dx-roast/, affiche le récapitulatif. Temps total <60s pour un dépôt typique.
Bonne comparaison :
« Audit DX du répertoire actuel. Référence par rapport à https://github.com/vercel/next.js. »
→ Analyse les deux, note l'actuel, inclut une ligne de référence dans le roast et le récapitulatif.
Ce que cette compétence NE fait PAS
- Ne modifie pas le dépôt cible (analyse en lecture seule)
- N'effectue pas d'audits de sécurité ou d'analyses de dépendances
- Ne génère pas de contenu marketing (les actions sont concrètes, pas « réécrire pour le ton »)
- Ne produit pas d'images ou d'actifs (juste des placeholders)
- Ne publie pas sur les réseaux sociaux (écrit uniquement du texte partageable)