dx-roaster
Crítica la experiencia del desarrollador de un repositorio de GitHub. Produce cuatro archivos: roast.md, action-plan.md, ideal-readme.md, score.json. Creado para mantenedores de OSS y fundadores de herramientas para desarrolladores que se preparan para Show HN, Product Hunt o cualquier lanzamiento donde los primeros cinco minutos importan.
Reglas críticas (leer antes de cada ejecución)
-
Lee los tres archivos de referencia ANTES de puntuar.
references/scoring-rubric.md,references/roast-voice-guide.md,references/readme-template.md. La rúbrica no es negociable: usa las 10 dimensiones exactas. -
Puntúa cada dimensión en la escala 0–10. Nunca omitas. Datos faltantes = puntuación 0, no "N/A".
-
La crítica debe citar hallazgos específicos. Cita líneas textuales malas. Haz referencia a las rutas de los archivos. Cita números de línea cuando sea posible. Nunca escribas lugares comunes genéricos como "la documentación podría ser mejor".
-
El tono importa. Por defecto
honest. Cambia la voz segúnreferences/roast-voice-guide.md. El tono brutal es divertido pero nunca personal. El tono amable es alentador pero sigue siendo específico. -
El plan de acción está ordenado por impacto, no por severidad. Usa
impacto × (1 / esfuerzo). Una solución de 5 minutos que suma 10 puntos está por encima de una solución de 2 horas que suma 12 puntos. -
Nunca inventes URLs. Al escribir
ideal-readme.md, usa la sintaxis<placeholder>para los enlaces faltantes. La crítica le dirá al mantenedor que los complete. -
Nunca nombres a los mantenedores o contribuyentes. Critica el trabajo, no a las personas.
-
Genera exactamente cuatro archivos en
dx-roast/. No escribas en otras ubicaciones. No omitas archivos.
Paso 1: Entrada
Requerido:
repo— ruta local (por defecto.) O URLhttps://github.com/owner/repo
Opcional:
| Parámetro | Por defecto | Descripción |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | Dónde escribir los 4 archivos de salida |
compare_to | ninguno | URL opcional de un segundo repositorio para comparación comparativa |
Si repo es una URL: clónalo a un directorio temporal usando git clone <url> /tmp/dx-roast-<hash-corto>. Escanea desde allí. Elimina el directorio temporal después de la ejecución.
Si repo es . o una ruta local: escanea en el lugar, no modifiques nada.
Paso 2: Descubrimiento
Lee estos archivos (cada uno puede estar ausente; anota la ausencia):
README.md— contenido completo, estructura (encabezados), bloques de código, referencias a imágenes, URLs de insigniasCONTRIBUTING.md,CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/,.github/PULL_REQUEST_TEMPLATE.md,.github/CODEOWNERSpackage.json(descripción, homepage, repository, license, scripts),pyproject.toml,Cargo.toml,go.modLICENSE(existencia + tipo)- Contenido de la carpeta
docs/(solo nombres de archivo + tamaños) - Carpeta
examples/osamples/ocookbook/ .github/workflows/*.yml(solo nombres + verificación breve de presencia de CI)
Si repo es una URL, también obtén datos mediante gh:
github api repos/<owner>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
github api repos/<owner>/<repo>/commits --jq '.[0].commit.author.date' | head -1
github api repos/<owner>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
Captura y continúa si alguna llamada de GitHub falla.
Paso 3: Puntuación de 10 dimensiones
Para cada una de las 10 dimensiones en references/scoring-rubric.md, genera {score: 0–10, evidence: [...]} donde evidence es una lista de 1 a 3 cadenas cortas que citen lo que encontraste.
Ejemplo:
"visual_proof": {
"score": 4,
"evidence": [
"Se encontró 1 captura de pantalla en la línea 89 (debajo del pliegue)",
"Sin demostración animada / gif",
"Sin video"
]
}
Suma las puntuaciones → total (0–100) → calificación (A/B/C/D/F según la rúbrica).
Guarda en dx-roast/score.json con esta forma exacta:
{
"repo": "<owner/repo o ruta local>",
"scanned_at": "<marca de tiempo 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"
}
Paso 4: Escribe la crítica
Lee references/roast-voice-guide.md. Aplica el tono solicitado. Escribe de 250 a 500 palabras en dx-roast/roast.md.
Estructura requerida:
# DX Roast: <nombre del repo>
**Calificación: <letra> (<total>/100)** · Tono: <tone>
<Párrafo 1: el veredicto. Lo que funciona + la gran brecha.>
<Párrafo 2: cita 2 hallazgos específicos con referencias a archivos.>
<Párrafo 3: cita 2 hallazgos más, relacionalos con las puntuaciones de las dimensiones.>
<Párrafo 4 (opcional): un giro final o comparación con un repositorio conocido como bueno.>
<Párrafo de cierre: apunta a `action-plan.md` para el camino a seguir.>
Cada crítica debe hacer referencia a al menos 3 hallazgos específicos de los arrays de evidencia de score.json.
Paso 5: Generar plan de acción
Calcula prioridad = impacto / minutos_esfuerzo para cada posible solución. Toma las 5–10 mejores. Ordena descendente por prioridad.
Para cada solución, escribe en dx-roast/action-plan.md:
### N. <Solución en voz imperativa, una línea>
**Por qué:** <Justificación de una oración. Haz referencia a qué dimensión mejora.>
**Impacto:** +<X> puntos · **Esfuerzo:** <5min / 30min / 2h / medio-día>
**Cómo:**
1. <Paso concreto 1>
2. <Paso concreto 2>
3. <Paso concreto 3>
<Fragmento de código/markdown opcional que muestre el cambio exacto>
Abre action-plan.md con:
# Plan de acción — <nombre del repo>
Calificación actual: <letra> (<total>/100)
Mejores soluciones ordenadas por impacto × esfuerzo. Hazlas en orden.
---
Paso 6: Generar README ideal
Lee references/readme-template.md. Completa la plantilla según la sección "Reglas de llenado". Escribe en dx-roast/ideal-readme.md.
Usa marcadores de posición <homepage_url> etc. para valores faltantes. Límite de longitud: 100 líneas.
Paso 7: Resumen en terminal
Imprime este formato exacto al usuario:
DX Roast completo — Calificación: <letra> (<total>/100)
3 mejores soluciones (ordenadas por impacto):
1. <solución 1> +<X> pts · <esfuerzo>
2. <solución 2> +<X> pts · <esfuerzo>
3. <solución 3> +<X> pts · <esfuerzo>
Archivos:
→ dx-roast/roast.md (veredicto compartible)
→ dx-roast/action-plan.md (soluciones priorizadas)
→ dx-roast/ideal-readme.md (estado objetivo)
→ dx-roast/score.json (puntuaciones crudas)
Si se proporcionó compare_to, agrega una línea de comparación:
Referencia: <otro repo> puntúa <X>/100 (calificación <Y>) — diferencia de <delta> puntos.
Auto-QA (cada ejecución, antes de imprimir el resumen en terminal)
- Las 10 dimensiones en
score.jsontienen puntuación + evidencia - El total es igual a la suma de las dimensiones
- La letra de calificación coincide con el total según los umbrales de la rúbrica
- La crítica hace referencia a al menos 3 elementos de evidencia de score.json
- La crítica no nombra a ningún mantenedor / contribuyente
- El plan de acción tiene 5–10 elementos, ordenados descendente por prioridad
- El README ideal tiene < 100 líneas
- El README ideal usa
<placeholder>para cualquier URL no encontrada en el escaneo - Los 4 archivos existen en output_dir
- No hay marcadores de posición
<TBD>/<TODO>en roast.md o action-plan.md
Si algún chequeo falla, corrige y vuelve a ejecutar ese paso.
Manejo de errores
Estos cuatro modos de fallo reciben un manejo explícito: nunca permitas que el skill produzca silenciosamente una salida parcial sin mostrar la causa.
| Caso | Comportamiento |
|---|---|
repo no existe O no se puede clonar O no se puede leer | Salir inmediatamente con el mensaje Repo no encontrado o inaccesible: <repo>. No escribir ningún archivo de salida. |
README.md falta | Ejecutar de todas formas. Puntuar what_is_this_clarity, visual_proof, runnable_quick_start y marketing_signals cerca de 0. Usar la ausencia como apertura de la crítica ("Sin README es una declaración en sí misma"). |
| El repo es privado + no hay autenticación de GitHub disponible | Intentar un clon local (git clone <url>); si falla, salir con El repo es privado y no hay autenticación disponible. Sugerir al usuario que configure GITHUB_TOKEN o pase una ruta local. |
La URL de compare_to falla (red, 404, privado, etc.) | Continuar sin la comparativa. Agregar una sola línea a la crítica: Nota: la comparativa solicitada contra <compare_to> no se pudo obtener. Omitir la línea Referencia: del resumen en terminal. |
Cualquier error de la API de GitHub (límite de tasa, 5xx transitorio) durante la obtención de metadatos del Paso 2 se captura y se registra en score.json bajo trust_signals.evidence como "metadatos de github no disponibles". El resto de la ejecución continúa.
Ejemplos
Buena invocación:
"Critica mi repo en https://github.com/myorg/mytool — tono: brutal."
→ El skill clona, escanea, puntúa, escribe 4 archivos en dx-roast/, imprime el resumen. Tiempo total de ejecución <60s para un repositorio típico.
Buena comparación:
"Auditoría DX en el directorio actual. Comparativa con https://github.com/vercel/next.js."
→ Escanea ambos, puntúa el actual, incluye línea de comparativa en la crítica y el resumen.
Lo que este skill NO hace
- No modifica el repositorio objetivo (escaneo de solo lectura)
- No realiza auditorías de seguridad ni escaneos de dependencias
- No genera copias de marketing (las acciones son concretas, no "reescribe para el tono")
- No produce imágenes ni activos (solo marcadores de posición)
- No publica en redes sociales (escribe solo texto compartible)