AlemTuzlak/skills

docs

Escreva documentação que uma pessoa real queira ler. Curta, simples, construída em torno de alguém tentando fazer algo real.

"Documentar a funcionalidade X" não é o trabalho. "Ajudar alguém a fazer Y com X" é o trabalho.

Trabalhe em duas fases. Primeiro planeje a história: quem lê isso, o que essa pessoa quer e quantas páginas devem ser. Depois escreva.

O plano não é privado. O usuário deve ver os leitores e deve escolher o tom antes que qualquer página seja escrita.

Encontrar documentação
  → ler páginas vizinhas
  → Fase 1: leitores + páginas
  → PORTÃO DAS PERSONAS (escreva a lista de leitores no chat, então pare)
  → PORTÃO DO TOM (escreva o tom no chat, então pare)   [ao escrever páginas]
  → carregar simple-english + i-have-adhd   [ao escrever páginas]
  → Fase 2: escrever

Uma lista de impacto na documentação dentro de um plano de funcionalidade ainda executa o portão das personas. Ela não executa o portão do tom nem carrega as habilidades de escrita até que as páginas sejam realmente escritas.

Quando executar

A documentação acompanha o código. Execute este skill em três momentos, não apenas quando solicitado.

• Alguém pede documentação. Escreva-a.
• Planejando uma funcionalidade ou alteração em um repositório. Antes que o plano seja concluído, liste quais documentos são novos e quais precisam de atualização. Esta lista de impacto na documentação faz parte do plano, assim como as alterações de código. Nomeie o leitor para cada página.
• Finalizando uma implementação. Escreva ou atualize essa documentação antes de considerar o trabalho concluído. Uma alteração na forma como algo se comporta que não acompanha nenhuma alteração na documentação não está concluída.

Habilidades necessárias para as páginas finais

simple-english e i-have-adhd são pré-requisitos. Eles se aplicam às páginas de documentação, não a este chat de planejamento.

Carregue ambos imediatamente antes de escrever o conteúdo da página. Use a ferramenta Skill se este harness tiver uma. Se não tiver, leia o SKILL.md de cada habilidade do diretório local de skills. Não escreva páginas a partir da memória dessas habilidades.

Se alguma das habilidades estiver faltando, pare e avise o usuário. Não escreva as páginas sem elas.

Como elas se compõem:

• Esta habilidade define para quem é a página, a divisão da página, problema-depois-solução, mostre-não-conte, sem vazamento de histórico, glifos proibidos e estrutura de vizinhança.
• simple-english controla as frases. Use o modo pragmático. Execute sua auto-verificação antes de considerar uma página concluída.
• i-have-adhd controla a forma da página: próxima ação primeiro, etapas numeradas, listas limitadas a 5 (divida entre obrigatório e posterior, ou divida a página), sem preâmbulo, uma vitória visível no final.

Quando i-have-adhd é carregado a partir deste skill, aplique-o apenas às páginas. Não mude o resto da sessão para o modo TDAH. A seção de persistência de i-have-adhd não se aplica aqui.

Encontre a documentação primeiro

Antes de escrever qualquer coisa, encontre onde a documentação está.

1. Procure por uma pasta de docs. Verifique docs/ primeiro, depois documentation/, content/docs/, site/, website/docs/.
2. Não encontrou nada? Pergunte ao usuário onde a documentação deve ficar. Não adivinhe e não crie uma pasta por palpite.
3. Abra 2 ou 3 páginas existentes próximas ao local onde o novo conteúdo deve pertencer. Leia-as para copiar a estrutura, o frontmatter e os componentes. Anote o tom aparente como um candidato para o portão do tom. Não o adote ainda.
4. Anote quais componentes o site já usa (etapas, abas, callouts, cards, accordions, grupos de código, etc.). Sites diferentes têm componentes diferentes.
5. Reutilize esses componentes para contar a história. Se o site tem um componente de etapas, use-o para tutoriais. Se tem abas, use-as para variações de framework. Se o site não tem nenhum, use markdown simples. Nunca invente um componente que o site não tenha.

Se não houver uma página como a que você está prestes a escrever, leia a mais próxima que encontrar e corresponda a ela.

O que "corresponder aos vizinhos" cobre, e o que não cobre

Corresponder aos vizinhos é sobre cópia, estrutura, frontmatter e componentes: se os cabeçalhos estão em maiúsculas/minúsculas, quanta configuração uma seção recebe, quais componentes conduzem o tutorial, como as amostras de código são introduzidas, quais são os campos do frontmatter.

Não é um substituto para o portão do tom. Vizinhos podem sugerir um padrão. Eles não podem responder pelo usuário.

Também não é permissão para copiar maus hábitos dos vizinhos. Tudo em Proibido e toda regra neste skill ainda se aplica ao conteúdo que você escreve, independentemente do que as páginas ao redor fazem. Uma página existente cheia de travessões não licencia mais um.

Portanto: nunca raciocine "as outras páginas fazem isso, então eu também farei" sobre uma regra que este skill estabelece. Se páginas existentes quebram uma regra e você acha que todo o conjunto deve ser alinhado, isso é uma limpeza separada a ser levantada com o usuário, não algo a ser resolvido silenciosamente correspondendo à violação.

Fase 1: planeje a história

Faça isso antes de escrever uma palavra de conteúdo.

1. Liste quem lê isso e o que cada um quer. Uma pessoa construindo em um React SPA, uma pessoa em um aplicativo renderizado no servidor, alguém que só quer uma demonstração rápida, alguém estendendo os internos. Não pare no primeiro leitor.
2. Escreva uma história de usuário por leitor: "Como um X, quero Y, para poder Z."
3. Transforme histórias em páginas. Uma jornada é uma página. Jornadas diferentes são páginas diferentes. Uma funcionalidade com três jornadas reais são três páginas mais talvez uma visão geral curta, não uma página gigante.
4. Verifique se todo leitor tem um caminho. Um leitor sem página é um buraco no plano. Adicione uma página ou uma rota para ele.

A divisão de páginas vem desta etapa. Não a pule.

Portão: mostre as personas

Ferramentas de pergunta (AskQuestion, ask_user_question e formas similares) não mostram seu payload no chat que o usuário lê. Uma interação que apenas chama uma dessas ferramentas falha neste portão. Pede-se ao usuário que confirme uma lista que ele não pode ver.

Após o passo 4, escreva uma mensagem de chat normal. O corpo da mensagem é obrigatório mesmo quando uma ferramenta de pergunta também é chamada. A mensagem contém:

1. Cada leitor, como seu próprio bloco curto que o usuário pode escanear:
   • Nome do leitor.
   • Uma história de usuário: "Como um X, quero Y, para poder Z."
   • A página que você escreverá para ele.
2. Uma pergunta, escrita nessa mesma mensagem: confirmar, remover um leitor, ou adicionar um.

Uma ferramenta de pergunta é opcional. Chame-a apenas depois que essa lista já estiver na mensagem do chat. A ferramenta pergunta apenas a escolha curta (confirmar, remover ou adicionar). Não coloque os nomes dos leitores, as histórias ou as páginas dentro da ferramenta. Se a ferramenta fosse a única saída da interação, não a chame. Escreva a mensagem.

Então escolha um caminho:

Padrão: pare. Esta mensagem é a interação inteira. Termine a interação. Não escreva arquivos. Não comece a Fase 2. Não diga que prosseguirá a menos que eles objetem.

Pular a espera: continue nesta mesma interação. Use este caminho apenas quando uma destas for verdadeira:

• Esta conversa já tem a confirmação do usuário desta lista de personas.
• O usuário disse "use padrões sensatos", "apenas escreva" ou "não faça perguntas". Ainda ASSIM MOSTRE a lista nesta interação, depois continue.
• A alteração é uma pequena edição de cópia: erro de digitação, link quebrado, linguagem de bloco de código, ou uma correção factual. Sem nova página, sem nova seção, sem reescrita de uma jornada.

Neste caminho, não termine a interação. Depois de mostrar a lista (ou depois de uma pequena edição de cópia, sem lista), continue para o próximo passo.

Estes não são pulos:

• "Os leitores são óbvios."
• "O usuário pediu documentação, então eles não querem uma pergunta."
• "Eu já os nomeei no plano."
• "Há apenas um leitor."
• "Isso é parte da implementação de uma funcionalidade, continue."
• "A ferramenta de pergunta mostrará a lista a eles." Não mostrará. A lista vai no chat.

Escrever documentação é a razão pela qual este portão existe. Não é uma razão para pulá-lo.

Menos é mais: divida, não amontoe

Não force milhares de palavras em uma página. Páginas longas escondem a resposta.

Quando um tópico tem vários ângulos, dê a cada um sua própria página curta e os vincule. Um leitor chega na visão geral e então clica exatamente no que precisa.

Exemplo. Uma funcionalidade para interrupções de ferramenta:

Ruim: uma página
  interrupts.md   (visão geral + caso simples + muitas interrupções + personalizado, tudo amontoado)

Bom: um pequeno conjunto de páginas vinculadas
  interrupts/index.md            o que é, quando usar, links para fora
  interrupts/basic.md            uma interrupção, do início ao fim
  interrupts/multiple.md         várias interrupções em um fluxo
  interrupts/custom.md           construa a sua

Cada página é curta e faz uma coisa. A visão geral as costura em uma história.

Portão: pergunte pelo tom

Este portão fica entre a Fase 1 e a Fase 2. Execute-o antes de escrever qualquer página. Não o aninhe dentro da Fase 2.

Vizinhos podem sugerir um padrão. Eles não podem responder pelo usuário.

Escreva uma mensagem de chat normal. O corpo da mensagem é obrigatório mesmo quando uma ferramenta de pergunta também é chamada. A mensagem contém:

1. O tom que você inferiu de páginas vizinhas, em uma linha (quão formal, quanta configuração, segunda pessoa ou não).
2. Uma pergunta, escrita nessa mesma mensagem: usar esse tom, mais casual, mais formal, ou o usuário nomeia outro.

Uma ferramenta de pergunta é opcional e vem depois que essa linha está no chat. A ferramenta pergunta apenas a escolha curta. Não coloque o tom inferido apenas dentro da ferramenta. Uma interação que apenas chama a ferramenta falha neste portão.

Então escolha um caminho:

Padrão: pare. Esta mensagem é a interação inteira. Termine a interação. Não escreva conteúdo de página.

Pular a espera: continue nesta mesma interação. Use este caminho apenas quando uma destas for verdadeira:

• Esta conversa já tem a escolha de tom do usuário, incluindo um explícito "corresponda às páginas existentes".
• O usuário disse "use padrões sensatos", "apenas escreva" ou "não faça perguntas". Ainda assim DECLARE o tom inferido em uma linha, depois continue.
• Pequena edição de cópia, mesma exceção do portão das personas.

Neste caminho, não termine a interação. Depois de declarar o tom (ou depois de uma pequena edição de cópia, sem pergunta), continue para a Fase 2.

Estes não são pulos:

• "Posso dizer pelos vizinhos."
• "O site já tem uma voz."
• "Tom não importa para uma página de referência."
• "Vou corresponder aos vizinhos e mencionar depois."

Fase 2: escreva como um humano

Não escreva conteúdo de página até que o portão das personas tenha passado, o portão do tom tenha passado e simple-english mais i-have-adhd estejam carregados.

O portão do tom é o título acima deste. Execute esse portão primeiro. Depois carregue as duas habilidades. Então escreva.

Legibilidade é o objetivo, acima de tudo.

• Mantenha digerível. Sem paredes de texto, sem parágrafos enormes. Divida ideias em pequenos pedaços. Dê a menor quantidade de informação que faça o trabalho.
• Frases seguem simple-english (modo pragmático). Não insira um substituto mais fraco inline.
• Mantenha o markdown leve. Listas são boas. Títulos em negrito em cada linha não são. Deixe as palavras carregarem a página.
• Prefira ASCII simples e caracteres normais de teclado a glifos sofisticados. Escreva da forma que uma pessoa digita.
• Segunda pessoa, ação primeiro. Comece com o que o leitor tem agora e o que terá no final. Sem aberturas do tipo "Neste guia vamos explorar...". Apenas comece.
• Molde a página com i-have-adhd: a primeira linha é algo que o leitor pode fazer, trabalho de várias etapas é numerado, uma lista com mais de 5 itens é dividida, a página termina com uma vitória visível.

Lidere com o problema, depois resolva-o

Toda página abre com o problema que o leitor veio resolver, em suas próprias palavras, antes de qualquer API. Nomeie a situação em que estão presos. Depois diga em uma ou duas frases como a funcionalidade o resolve. Só então entre nas partes técnicas e no código.

Um leitor que vê o problema primeiro sabe em segundos se está na página certa. Um leitor que vê uma assinatura de API primeiro precisa engenharia reversa para descobrir para que serve.

A primeira linha do "como" é a próxima ação (de i-have-adhd). O problema ainda vem primeiro para que saibam que estão na página certa.

Ruim:
  Chame useInterrupts() e passe um resolver. O resolver executa uma vez por
  item pendente dentro de uma transação...

Bom:
  Algumas chamadas de ferramenta não devem ser executadas sem que um humano diga sim: mover dinheiro, 
  deletar dados. Uma interrupção pausa a execução para essa decisão, depois retoma de onde parou. 
  Aqui está como proteger uma ferramenta por trás de uma aprovação:

  [código]

A ordem para um guia é problema, correção em uma linha, depois o "como" (etapas, trechos, API). Mantenha o problema em algumas frases, não um ensaio de fundo. O código mostra como é resolvido, então não narre a solução em prosa primeiro.

Mostre, não conte

Não explique em quatro parágrafos o que uma frase e um bloco de código podem mostrar. Leitores entendem um diff ou um trecho mais rápido do que prosa.

Ruim:
  Três parágrafos descrevendo como o objeto de config aceita um array de
  middleware, o que cada slot faz e como a ordenação funciona.

Bom:
  Adicione seu middleware ao array `middleware`. A ordem executa de cima para baixo:

  const app = createApp({
    middleware: [auth, logging],
  })

Um bom exemplo executável vale mais que uma página de descrição. Toda amostra de código deve funcionar quando copiada, não precisar de imaginação para preencher lacunas.

Liste tudo que é uma lista

No momento em que uma frase cobre mais de um item, opção, armazenamento, flag ou etapa, ela se torna uma lista. Não os encadeie em um parágrafo com vírgulas e ponto e vírgula. Um leitor escaneando uma lista com marcadores encontra seu item em um segundo. Em um parágrafo, eles precisam ler tudo para saber que não se aplica a eles.

O sinal é uma frase que nomeia duas ou mais coisas e diz algo sobre cada uma. Corte-a em um marcador por coisa, uma ou duas frases cada.

Ruim:
  Cada armazenamento é independente. Forneça apenas os que precisa. Para chat:
  `messages` para o transcript, `runs` para o ciclo de vida da execução, `interrupts` para 
  aprovações duráveis (precisa de `runs`), `metadata` para estado chave/valor com namespace.
  Para geração: `generationRuns` para o ciclo de vida da execução, mais `artifacts` e
  `blobs` para manter bytes gerados.

Bom:
  Cada armazenamento é independente, então forneça apenas os que precisa.

  Para chat:

  - `messages`: o transcript.
  - `runs`: ciclo de vida da execução.
  - `interrupts`: aprovações duráveis. Precisa de `runs`.
  - `metadata`: estado chave/valor com namespace.

  Para geração:

  - `generationRuns`: ciclo de vida da execução.
  - `artifacts`: artefatos gerados.
  - `blobs`: blobs gerados.

Não há exceção para este padrão. Cada vez que você escreve "e", "ou" ou uma vírgula separando itens paralelos, faça uma lista.

Proibido

Estes glifos, símbolos e padrões são proibidos em toda página que este skill escreve. Eles não aparecem no resultado.

• Traço – – (U+2013). Escreva o hífen - (U+002D) que está no teclado.
• Traço — — (U+2014). Mesmo. Hífen simples.
• Aspas curvas “ ” “ ” (U+201C, U+201D). Use aspas retas " (U+0022) que estão no teclado.
• Aspas curvas simples ‘ ’ ‘ ’ (U+2018, U+2019). Use apóstrofo reto ' (U+0027).
• Elipse … … (U+2026). Escreva três pontos ... (três caracteres U+002E).
• Símbolo de direitos autorais © © (U+00A9). Escreva (c).
• Símbolo de marca registrada ® ® (U+00AE). Escreva (r).
• Símbolo de marca comercial ™ ™ (U+2122). Escreva (tm).
• Seta → → (U+2192). Escreva ->.
• Seta ⇒ ⇒ (U+21D2). Escreva =>.
• Bullet • • (U+2022). Use o bullet padrão do markdown -.
• Bullet de item de sublista: mesclado com travessão - no markdown, não um caractere especial.
• Espaço inquebrável   (U+00A0). Use espaço normal.
• Sinal de parágrafo ¶ ¶ (U+00B6). Não use.
• Sinal de seção § § (U+00A7). Não use.
• Acento circunflexo ^ ^ (U+005E) usado como cabeçalho. Use # para cabeçalhos.
• Separação visual ou horizontal com * * *, --- ou ___ não é proibida, mas use com moderação. Prefira uma quebra de seção com um cabeçalho.
• Aspas angulares «» para citação. Use o caractere de citação do markdown >.
• e.g. e i.e. - escreva por extenso: "por exemplo" e "isto é". Abreviações latinas são menos legíveis.
• etc. - escreva "e assim por diante" ou reestruture para não precisar.
• Notas de rodapé [^1] em markdown. Coloque o conteúdo diretamente no texto ou como uma nota lateral.
• Âncoras de link vazias [](url). Sempre forneça texto de link descritivo.
• Imagens com texto alternativo vazio ![]() ou sem texto alternativo. Sempre forneça texto alternativo que descreva a imagem.

A lista de glifos não é exaustiva. Como regra geral: escreva usando apenas caracteres que podem ser digitados em um teclado padrão US. Caracteres unicode que não podem ser digitados em um teclado padrão US (por exemplo, letras acentuadas, símbolos de moeda diferentes de $, etc.) são proibidos, a menos que façam parte de código literal (por exemplo, uma string de exemplo) ou de um nome próprio (por exemplo, uma marca). Glifos proibidos às vezes aparecem dentro de blocos de código, nomes de arquivos e caminhos como parte de nomes de API ou texto de exemplo — isso é permitido. A regra se aplica ao texto da documentação que você escreve.

Se você encontrar um glifo proibido em uma página existente

Se você está editando uma página existente que contém um glifo proibido, não o introduza. Se for viável, substitua-o pela alternativa aprovada. Se a página existente usa um travessão, troque-o por um hífen. Se a página tem aspas curvas, troque por retas.

Se a página for um documento de terceiros ou um arquivo de configuração que não deve ser modificado cosmeticamente, deixe-o como está.

Notas de implementação

Sobre ferramentas de pergunta e paradas

O portão das personas e o portão do tom são implementados por este skill. Quando um harness específico tem um sistema de gates, usá-los é aceitável, desde que os portões descritos aqui ainda executem seu propósito: o usuário vê a lista e escolhe o tom antes que o conteúdo da página seja escrito.

Quando este skill instrui "escreva uma mensagem de chat normal" e "termine a interação", a implementação deve usar o mecanismo do agente para parar. Se o agente não pode parar sem conteúdo, escreva a mensagem e emita uma parada artificial. Se uma ferramenta de pergunta é necessária para colher a resposta do usuário, a implementação deve garantir que a lista já está no chat antes de chamar a ferramenta.

O padrão geral: toda vez que um portão diz "pare", o estado do mundo neste turno contém a mensagem com a lista ou com o tom. A saída não contém conteúdo de página. A implementação não ignora o portão porque o agente se sente pressionado a continuar.

Um fluxo de trabalho típico que os agentes seguem

1. Alguém pede documentação ou uma nova funcionalidade.
2. O agente executa Find the docs first para localizar a documentação.
3. O agente executa Phase 1: plan the story para identificar leitores e divisão de páginas.
4. O agente executa Gate: show the personas para mostrar a lista de leitores.
5. Opcionalmente, o agente para e espera a resposta do usuário.
6. O agente executa Gate: ask for tone para determinar o tom.
7. Opcionalmente, o agente para e espera a resposta do usuário.
8. O agente carrega simple-english e i-have-adhd.
9. O agente executa Phase 2: write like a human para escrever o conteúdo da página.
10. O agente verifica glifos proibidos e aplica regras de formato.
11. O agente escreve os arquivos no sistema de arquivos.