dx-roaster
Analisa e critica a experiência do desenvolvedor (DX) de um repositório GitHub. Produz quatro arquivos: roast.md, action-plan.md, ideal-readme.md, score.json. Criado para mantenedores de OSS e fundadores de ferramentas dev que se preparam para Show HN, Product Hunt ou qualquer lançamento onde os primeiros cinco minutos importam.
Regras críticas (leia antes de cada execução)
-
Leia todos os três arquivos de referência ANTES de pontuar.
references/scoring-rubric.md,references/roast-voice-guide.md,references/readme-template.md. A rubrica é inegociável — use as 10 dimensões exatas. -
Pontue cada dimensão na escala de 0–10. Nunca pule. Dados ausentes = nota 0, não "N/A".
-
A crítica deve citar descobertas específicas. Cite linhas ruins textualmente. Referencie caminhos de arquivos. Cite números de linha quando possível. Nunca escreva lugares-comuns genéricos como "a documentação poderia ser melhor".
-
O tom importa. Padrão
honest. Mude a voz conformereferences/roast-voice-guide.md. O tom brutal é engraçado, mas nunca pessoal. O tom gentil é encorajador, mas ainda específico. -
O plano de ação é ordenado por impacto, não por severidade. Use
impacto × (1 / esforço). Uma correção de 5 minutos que adiciona 10 pontos fica acima de uma correção de 2 horas que adiciona 12 pontos. -
Nunca invente URLs. Ao escrever
ideal-readme.md, use a sintaxe<placeholder>para links ausentes. A crítica dirá ao mantenedor para preencher. -
Nunca nomeie mantenedores ou contribuidores. Critique o trabalho, não as pessoas.
-
Produza exatamente quatro arquivos em
dx-roast/. Não escreva em outros locais. Não pule arquivos.
Etapa 1: Entrada
Obrigatório:
repo— caminho local (padrão.) OU URLhttps://github.com/owner/repo
Opcional:
| Parâmetro | Padrão | Descrição |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | Onde escrever os 4 arquivos de saída |
compare_to | nenhum | URL opcional de um segundo repositório para comparação de benchmark |
Se repo for uma URL: clone para um diretório temporário usando git clone <url> /tmp/dx-roast-<hash-curto>. Escaneie a partir daí. Exclua o diretório temporário após a execução.
Se repo for . ou um caminho local: escaneie no local, não modifique nada.
Etapa 2: Descoberta
Leia estes arquivos (cada um pode estar ausente — anote a ausência):
README.md— conteúdo completo, estrutura (cabeçalhos), blocos de código, referências de imagem, URLs de badgesCONTRIBUTING.md,CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/,.github/PULL_REQUEST_TEMPLATE.md,.github/CODEOWNERSpackage.json(descrição, homepage, repositório, licença, scripts),pyproject.toml,Cargo.toml,go.modLICENSE(existência + tipo)- Conteúdo da pasta
docs/(apenas nomes de arquivos + tamanhos) - Pasta
examples/ousamples/oucookbook/ .github/workflows/*.yml(apenas nomes + verificação breve da presença de CI)
Se repo for uma URL, também busque via gh:
gh 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'
Capture e continue se alguma chamada ao GitHub falhar.
Etapa 3: Pontuar 10 dimensões
Para cada uma das 10 dimensões em references/scoring-rubric.md, produza {score: 0–10, evidence: [...]} onde evidence é uma lista de 1–3 strings curtas citando o que você encontrou.
Exemplo:
"visual_proof": {
"score": 4,
"evidence": [
"Encontrei 1 captura de tela na linha 89 (abaixo da dobra)",
"Nenhuma demonstração animada / gif",
"Nenhum vídeo"
]
}
Some as notas → total (0–100) → nota (A/B/C/D/F conforme rubrica).
Salve em dx-roast/score.json com este formato exato:
{
"repo": "<owner/repo ou caminho local>",
"scanned_at": "<carimbo de data/hora 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"
}
Etapa 4: Escrever a crítica
Leia references/roast-voice-guide.md. Aplique o tom solicitado. Escreva 250–500 palavras em dx-roast/roast.md.
Estrutura obrigatória:
# DX Roast: <nome do repositório>
**Nota: <letra> (<total>/100)** · Tom: <tone>
<Parágrafo 1: o veredito. O que funciona + a grande lacuna.>
<Parágrafo 2: cite 2 descobertas específicas com referências a arquivos.>
<Parágrafo 3: cite mais 2 descobertas, relacione às notas das dimensões.>
<Parágrafo 4 (opcional): um toque final ou comparação com um repositório conhecido e bom.>
<Parágrafo de encerramento: aponte para `action-plan.md` para o caminho a seguir.>
Toda crítica deve referenciar pelo menos 3 descobertas específicas dos arrays de evidências de score.json.
Etapa 5: Gerar plano de ação
Calcule prioridade = impacto / minutos_de_esforço para cada correção candidata. Pegue as 5–10 principais. Ordene decrescente por prioridade.
Para cada correção, escreva em dx-roast/action-plan.md:
### N. <Correção no modo imperativo, uma linha>
**Por quê:** <Justificativa de uma frase. Referencie qual dimensão melhora.>
**Impacto:** +<X> pontos · **Esforço:** <5min / 30min / 2h / meio-dia>
**Como:**
1. <Passo concreto 1>
2. <Passo concreto 2>
3. <Passo concreto 3>
<Snippet opcional de código/markdown mostrando a alteração exata>
Abra action-plan.md com:
# Plano de Ação — <nome do repositório>
Nota atual: <letra> (<total>/100)
Principais correções classificadas por impacto × esforço. Faça estas em ordem.
---
Etapa 6: Gerar README ideal
Leia references/readme-template.md. Preencha o modelo conforme a seção "Regras de preenchimento". Escreva em dx-roast/ideal-readme.md.
Use placeholders <homepage_url> etc. para valores ausentes. Limite de comprimento: 100 linhas.
Etapa 7: Resumo no terminal
Imprima este formato exato para o usuário:
DX Roast concluído — Nota: <letra> (<total>/100)
Top 3 correções (classificadas por impacto):
1. <correção 1> +<X> pts · <esforço>
2. <correção 2> +<X> pts · <esforço>
3. <correção 3> +<X> pts · <esforço>
Arquivos:
→ dx-roast/roast.md (veredito compartilhável)
→ dx-roast/action-plan.md (correções priorizadas)
→ dx-roast/ideal-readme.md (estado desejado)
→ dx-roast/score.json (notas brutas)
Se compare_to foi fornecido, adicione uma linha de comparação:
Benchmark: <outro repositório> pontua <X>/100 (nota <Y>) — diferença de <delta> pontos.
Auto-QA (toda execução, antes de imprimir o resumo no terminal)
- Todas as 10 dimensões em
score.jsontêm nota + evidências - Total é igual à soma das dimensões
- A letra da nota corresponde aos limites da rubrica
- A crítica referencia pelo menos 3 itens de evidência de score.json
- A crítica não nomeia nenhum mantenedor / contribuidor
- O plano de ação tem 5–10 itens, ordenados decrescente por prioridade
- O README ideal tem < 100 linhas
- O README ideal usa
<placeholder>para qualquer URL não encontrada na varredura - Todos os 4 arquivos existem em output_dir
- Nenhum placeholder
<TBD>/<TODO>em roast.md ou action-plan.md
Se alguma verificação falhar, corrija e reexecute essa etapa.
Tratamento de erros
Estes quatro modos de falha têm tratamento explícito — nunca deixe a skill produzir uma saída parcial silenciosamente sem revelar a causa.
| Caso | Comportamento |
|---|---|
repo não existe OU não pode ser clonado OU não pode ser lido | Saia imediatamente com a mensagem Repositório não encontrado ou inacessível: <repo>. Não escreva nenhum arquivo de saída. |
README.md está ausente | Execute mesmo assim. Pontue what_is_this_clarity, visual_proof, runnable_quick_start e marketing_signals perto de 0. Use a ausência como abertura da crítica ("Nenhum README é uma declaração por si só"). |
| Repositório é privado e nenhuma autenticação GitHub disponível | Tente um clone local (git clone <url>); se falhar, saia com O repositório é privado e nenhuma autenticação está disponível. Sugira que o usuário defina GITHUB_TOKEN ou passe um caminho local. |
URL de compare_to falha (rede, 404, privado, etc.) | Continue sem o benchmark. Adicione uma única linha à crítica: Nota: o benchmark solicitado contra <compare_to> não pôde ser obtido. Omita a linha Benchmark: do resumo no terminal. |
Qualquer erro da API do GitHub (limite de taxa, 5xx transitório) durante a busca de metadados da Etapa 2 é capturado e registrado em score.json sob trust_signals.evidence como "metadados do github indisponíveis". O restante da execução prossegue.
Exemplos
Invocação boa:
"Critique meu repositório em https://github.com/minhaorg/minhaferramenta — tom: brutal."
→ Skill clona, escaneia, pontua, escreve 4 arquivos em dx-roast/, imprime resumo. Tempo total de execução <60s para um repositório típico.
Comparação boa:
"Auditoria DX no diretório atual. Benchmark contra https://github.com/vercel/next.js."
→ Escaneia ambos, pontua o atual, inclui linha de benchmark na crítica e no resumo.
O que esta skill NÃO faz
- Não modifica o repositório alvo (varredura somente leitura)
- Não executa auditorias de segurança ou varreduras de dependências
- Não gera copy de marketing (itens de ação são concretos, não "reescreva para tom")
- Não produz imagens ou ativos (apenas placeholders)
- Não publica em mídias sociais (escreve apenas texto compartilhável)