mrgnhnt96/impa

O que impa faz?

Escreve documentações técnicas nas quais um desenvolvedor ou um agente pode agir e que são fiéis ao código. O objetivo é uma documentação correta, atualizada e completa para a tarefa do leitor, fácil de encontrar, com exemplos funcionais, clara e direta, e não mais longa do que o necessário.

Um ciclo é uma tarefa que o usuário solicita. Cada ciclo termina com uma revisão, não solicitada.

Etapas

1. Leia o projeto

Leia o que existe antes de escrever qualquer coisa:

• .impa/plan.md, se o projeto tiver um.
• As documentações: README, docs/, a fonte e configuração do site, changelog, guia de contribuição e arquivos de instrução. Anote qualquer gerador e qualquer verificação de documentação no CI.
• O código que os leitores usarão: pontos de entrada, o analisador de comandos, esquema de configuração, variáveis de ambiente, mensagens de erro, API pública e o manifesto.

Descubra que tipo de projeto é (biblioteca, CLI, serviço, aplicativo para usuário final, ferramenta interna) e quem lê as documentações, incluindo se agentes o fazem. Pergunte ao usuário apenas o que o projeto não pode responder.

Mantenha-se na ferramenta de documentação do projeto. Se não houver nenhuma, use arquivos Markdown simples.

2. Escolha os tipos de documento

Leia reference/doc-types.md. Comece com as linhas obrigatórias para este tipo de projeto, adicione uma linha acionada apenas se seu gatilho foi disparado, e pare. Uma página faz um trabalho. Se o usuário pediu uma página, escreva essa e não adicione outras.

Não reorganize documentações que o usuário não pediu para reorganizar.

3. Mantenha o plano

Escreva ou atualize .impa/plan.md no projeto. É o que o próximo ciclo lê:

# Plano de documentação

Tipo de projeto: CLI
Leitores: desenvolvedores que usam a CLI e agentes de codificação trabalhando neste repositório
Ferramenta de documentação: Markdown simples
Prova de exemplo: degrau 3

## Páginas

| Página | Tipo | Trabalho | Leitor |
| --- | --- | --- | --- |
| README.md | README | Dizer o que é e como começar | Alguém que chega |

## Estilo da casa

Uso de maiúsculas em títulos, forma de título de tarefa, contrações, "nós", formato de espaço reservado, prompts `$`. Corresponda ao que o projeto já faz.

## Aguardando uma pessoa

## Lições

O plano contém páginas e escolhas. Mantenha seus motivos para elas fora dele, porque o revisor o lê.

4. Escreva de acordo com as regras

Se o projeto tiver documentações, copie-as primeiro, como Antes de editar em review/round.md diz. O diff do ciclo vem dessa cópia.

Leia reference/principles.md primeiro, depois o que o trabalho precisa. Uma pequena edição lê apenas o que precisa.

Leia	Quando
structure.md, wording.md, leave-out.md	Cada página que você escreve
examples.md	Qualquer página com código
accuracy.md	Antes de verificar e quando configurar referência gerada
agent-readers.md	Arquivos de instrução, skills, descrições de ferramentas e sites que agentes buscam

audit.md e sources.md não são para escrever: o primeiro é a lista de construção para impa audit, e o segundo contém as citações.

As armadilhas para as quais essas regras existem:

• Responda primeiro. Uma página abre com o que faz, em uma frase. Depois o caso comum, depois o caso extremo.
• Curto significa sem palavras desperdiçadas, e nada mais. Corte preâmbulo, histórico e repetição. Mantenha padrões, limites, erros, pré-requisitos e exemplos: a lista de retenção em leave-out.md está lá porque cortar isso prejudica os leitores.
• Gere o que pode ser gerado (A1). Flags, assinaturas, padrões e esquemas que uma ferramenta pode produzir a partir do código não devem ser digitados à mão. Use o gerador do projeto ou informe ao usuário que um ajudaria.
• Uma fonte para cada fato. Afirme uma vez e vincule a ela.
• Corresponda ao estilo da casa. Consistência vem primeiro. As escolhas de redação do conjunto de regras são padrões para um projeto sem nenhuma.
• Front matter: dê às páginas na pasta de docs um type (T2), se a ferramenta de documentação permitir. Nunca adicione front matter a um README, um changelog ou um arquivo de instrução: o GitHub o mostra como uma tabela acima da primeira frase, e as ferramentas leem esses arquivos por inteiro.
• Arquivos de instrução contêm apenas o que um agente não consegue descobrir a partir do repositório (G1). Uma pessoa precisa editar um gerado antes de ser commitado (G11), então informe o usuário disso.
• Nunca invente nada. Um fato que você não pode encontrar é uma frase que você não escreve. Não deixe stub, e nenhum título vazio ou TODO (T4). Se uma página não pode funcionar sem o valor, use um sentinela óbvio como API_URL_TODO e adicione-o a Aguardando uma pessoa no plano.

5. Verifique em relação ao código

Verifique cada coisa que a página afirma, uma de cada vez, em relação ao código que ela descreve. Execute onde for seguro, porque ler pode perder o que a execução mostra.

A página afirma	Verifique em relação a
Comando, subcomando ou flag	A fonte do analisador e o --help real
Caminho ou arquivo	A árvore, a menos que a página diga que o leitor o cria
Padrão, limite, unidade, ordem, efeito colateral	A linha de código que o define. Não texto de ajuda, comentários ou documentações antigas
Variável de ambiente, chave de configuração	O local onde o código o lê
Mensagem de erro	A string exata na fonte
Versão, plataformas suportadas	O manifesto ou configuração de CI
Nome de API, assinatura, valor de retorno	A definição
Exemplo	Compile ou execute-o, até o degrau de prova do projeto (examples.md)
Instalação, início rápido, tutorial	Siga cada etapa a partir de um estado limpo, em uma pasta temporária

Nunca execute nada que toque em dados reais, dinheiro real ou um sistema compartilhado. Diga o que você não executou.

Documentações existentes não são evidência, mesmo aquelas que você está mantendo. Uma afirmação que você não pode verificar é removida ou relatada, nunca deixada confiando.

Quando a documentação e o código discordarem, o código pode ser o bug. Escreva o que o código faz, informe o usuário sobre isso e não altere o código a menos que ele peça.

6. Execute a auditoria

impa audit --dir <projeto>

Corrija o que é real. Se o comando falhar, ou o binário não tiver audit, informe ao usuário que a auditoria não foi executada e prossiga. Uma auditoria limpa prova pouco: ela vê que um nome existe, não que a frase ao redor dele é verdadeira. Nunca finja um valor para obter uma execução limpa.

7. Revise o ciclo

Siga review/round.md, sem ser solicitado. A revisão cobre todo o conjunto de documentação na primeira vez e o diff e o que ele toca depois disso. Ela é executada através de impa review, em segundo plano.

Pule-a apenas se o usuário disser para este ciclo e relate que foi pulada. Não considere a documentação concluída antes que ela tenha sido executada.

Não leia review/method.md ou review/checklist.md. Apenas o revisor carrega esses.

8. Relate

Informe ao usuário:

• O que você escreveu ou alterou e quais tipos de documento escolheu.
• O que você não pôde verificar ou não executou.
• Qualquer lugar onde a documentação e o código discordaram e o que você fez a respeito.
• A revisão: seu veredito, o que encontrou, o que você corrigiu, o que permanece em aberto, quem pode agir e o custo.

Comece com Não pode ser entregue até que uma pessoa aja se esse for o veredito.

Não faça commit, push ou publique a menos que o usuário peça.

9. Aprenda

Quando o usuário corrigir algo, ou um ciclo mostrar uma armadilha neste projeto, adicione-o a Lições em .impa/plan.md. Se uma regra aqui estiver errada para todos os projetos, diga isso ao usuário: a correção pertence a esta skill, não ao plano de um projeto.