ramon-sg/agent-skills

Explicar em simples

A meta: quem lê entende o importante em menos de um minuto. Na tela se lê pouco (cerca de 20 % do texto) e acima de tudo o começo de cada linha, então o importante vai primeiro e cada título diz algo.

Regras de estilo

Valem em todos os modos:

1. A primeira frase diz a decisão ou a resposta. O contexto vem depois.
2. Orações de 25 palavras ou menos, idealmente 15 a 20, com uma ideia cada uma.
3. Sujeito, verbo e complemento, em voz ativa, com quem faz o quê ("O servidor tenta novamente", não "Tenta-se novamente").
4. Palavras do dia a dia. Cliente, sessão, aviso, servidor, banco de dados estão bem. Nomes de função, arquivo ou variável não vão: vivem no detalhe.
5. Um caso concreto vale mais que uma descrição geral: um ator, o que faz e o que vê.
6. Títulos com conteúdo: "Hoje: os avisos se perdem", não "Como é hoje". As duas primeiras palavras dizem algo próprio deste texto.
7. Sem enchimento nem promoção: fora "basicamente", "simplesmente", "talvez", "em princípio", "robusto", "poderoso".
8. Listas só para coisas paralelas, sem aninhar, e parágrafos de três orações no máximo.
9. O ruim também se diz: o risco que se aceita, comparado com a alternativa, e o que fica de fora.

Modo documento: plano

A forma exata e os limites estão na skill planning (passo 2, "Em simples") e os verifica o check-plan.sh: "Decisão", "Hoje", "Depois", "Risco" e "Novo" opcionais, "Fora". Cada fato de "Hoje" liga à sua evidência e cada resultado de "Depois" à sua etapa.

"Novo" só vai depois de buscar o padrão no repositório (rg): um "isto é novo" falso tira a credibilidade de todo o plano.

Modo documento: issue

O cabeçalho da issue são três linhas, antes de tudo o mais. A forma completa está na skill github-issues.

**O que falha:** <ator e efeito, em uma frase>.      (ou **O que se pede:**)
**Por que importa:** <uma frase, com um número ou um caso>.
**Feito quando:** <o resultado observável principal>.

Modo lista (padrão na conversa)

Alguém pede que lhe expliquem algo, sem documento no meio:

• Um item por ideia, de 3 a 7 itens; se houver mais, agrupam-se.
• Todos começam com o mesmo tipo de palavra (todos com verbo ou todos com substantivo). As condições vão no fim ("…se o banco recusar").
• Sem títulos, sem negritos e sem forçar antes e depois: responde-se o que foi perguntado.
• Se a resposta é uma única ideia, vai direta, sem marcador.

Exemplo: "como funcionam as tentativas de pagamento?"

- Cobra o valor assim que o cliente toca "Pagar".
- Mostra "Tentar pagamento novamente" se o banco recusa por falta de fundos.
- Tenta novamente só até três vezes, com espera crescente, se a rede falhar.
- Registra cada tentativa falha no pedido, com o motivo.

Modo prosa

O mesmo, em parágrafos curtos. Só se pedirem ("conta-me corrido") ou se os itens não se entendem sem ler o anterior.

Exemplo: antes e depois

Antes (difícil de entender):

1. Como é hoje

• O RetryLink aplica maxRetries=3 por operação, o que, somado à ausência de um mecanismo de coordenação global, pode derivar em uma amplificação de carga significativa durante incidentes.

Depois:

Decisão: a app deixará de tentar novamente quando a API estiver caída.

Hoje: uma queda multiplica a carga

Cada consulta tenta novamente três vezes por conta própria. Se a API cair, recebe o triplo de pedidos justo quando tenta voltar.