G1en-114/rtfm-first-skill

RTFM-First

Use o manual fornecido pelo usuário como a única fonte autoritária para esta tarefa. Não escreva código baseado em memória ou em informações da internet.

Regras de Ferro

1. Quando o manual existir, leia-o primeiro antes de escrever código; nomes de API, parâmetros, valores padrão, unidades e comportamentos devem seguir o manual.
2. Antes de codificar, verifique a versão do manual contra a versão do ambiente atual (veja "Examinar ambiente e verificar versão") e relate a conclusão ao usuário.
3. Ao citar fatos importantes do manual, forneça a fonte: .rtfm/<nome>.txt:linha ou PÁGINA n.
4. Se o manual contradizer o código ou ambiente, não "corrija" imediatamente o código para corresponder às convenções da internet; pare, explique a diferença e deixe o usuário decidir.
5. Na ausência de um manual, solicite ou confirme o caminho do manual primeiro; não comece a implementar baseado em memória.
6. Antes de cada "correção", aponte qual regra do manual está sendo violada; sem fonte, não é permitido alterar.

Fluxo de Trabalho

1. Localizar e Extrair o Manual

• Se o usuário não fornecer o caminho, pesquise no projeto por candidatos (*.pdf, *.md, docs/**, especificações mencionadas no README); se houver vários, liste-os e peça confirmação ao usuário.
• Os scripts estão localizados no diretório scripts/ que acompanha este SKILL.md.
• Extraia de forma padronizada para .rtfm/ na raiz do projeto (se for um repositório git, certifique-se de que .gitignore inclua .rtfm/):
  • PDF: execute scripts/extract_manual.py <manual.pdf> .rtfm/<nome>.txt
  • MD/TXT: execute o mesmo script; ele copiará como texto.
• Se houver vários manuais (por exemplo, Referência de API + Especificação de Protocolo + Documentação do SDK), extraia todos e indexe cada um; ao citar, indique qual manual.
• Se o PDF for uma digitalização (texto extraído muito curto), informe que é necessário OCR, não tente adivinhar o conteúdo.
• Se o script reclamar "Nenhum extrator de texto PDF", instale poppler-utils ou pypdf conforme instruído (solicite permissão do usuário para instalação em nível de sistema) e tente novamente; não pule o PDF e escreva baseado na memória.
• Primeiro, leia a página de título / prefácio / histórico de versões, registrando: nome do produto, versão do manual, versões aplicáveis, data e notas de revisão.

2. Criar Índice

• Execute scripts/index_manual.py .rtfm/<nome>.txt .rtfm/index.md.
• Ao procurar qualquer tópico, use rg -n no índice e no texto completo; não presuma que o manual não cobre algo por "não lembrar".

3. Examinar Ambiente e Verificar Versão

• Colete evidências do ambiente: arquivos de manifesto/bloqueio (package.json, pyproject.toml, Cargo.lock, go.mod, requirements*.txt, etc.), --version/-V, pkg-config --modversion, versão do runtime, identificadores de SDK/ferramentas/hardware.
• Encontre a versão do manual na capa, histórico de versões, rodapé ou metadados.
• Determine MATCH / COMPATIBLE / MISMATCH / UNKNOWN de acordo com references/version-matching.md.
• Escreva a conclusão em .rtfm/version-report.md e relate ao usuário.
• Se for MISMATCH ou UNKNOWN, pare: peça ao usuário um manual de versão correspondente ou autorização explícita para prosseguir; se autorizado, registre o risco em .rtfm/notes.md.

4. Codificar de Acordo com o Manual

• Antes de trabalhar em cada componente/API, leia a seção relevante por completo; extraia assinaturas importantes, constantes, valores padrão e casos limite para .rtfm/notes.md, anexando a fonte.
• Estrutura sugerida para .rtfm/notes.md: nome do manual e versão, conclusão da verificação de versão (MATCH/COMPATIBLE/MISMATCH/UNKNOWN), anotações por tópico (cada uma com manual.txt:Llinha ou PÁGINA n), histórico de alterações.
• Copie identificadores, strings, números diretamente do manual para evitar erros de transcrição.
• Para pontos não cobertos pelo manual, marque TODO + fonte ("Seção X do manual não cobre"), não complemente silenciosamente com dados da internet; se necessário, solicite aprovação do usuário.
• O manual é a palavra final: mesmo que difira das "melhores práticas" online, não o "corrija" repetidamente para a versão online, a menos que o usuário solicite ou que evidências de compilação/teste provem que a página do manual não corresponde ao ambiente atual.

5. Verificar e Finalizar

• Após a conclusão, verifique cada seção contra o manual: cada API/configuração/comportamento usado deve ter fonte em .rtfm/notes.md.
• Execute a compilação/teste; em caso de falha, primeiro consulte a seção relevante do manual para encontrar a causa, depois verifique o ambiente; é proibido adivinhar.
• Na entrega, liste resumidamente: versão do manual, versão do ambiente, conclusão da verificação, principais fontes e quaisquer divergências que exijam confirmação do usuário.

Proteção Contra Loop de Correção

A razão direta para a existência desta skill: a IA não lê o manual → "corrige" código baseado em memória da internet → erra novamente → corrige de novo, reescrevendo repetidamente. As seguintes regras são obrigatórias:

• Prove antes de modificar: Antes de cada alteração no código/configuração, aponte "a implementação atual viola a linha X do manual" e cite a fonte; sem fonte, não altere.
• Uma alteração por motivo: Não misture "não parece certo" e "inconsistente com o manual" na mesma alteração; código não relacionado deve permanecer inalterado.
• Mesmo fenômeno aparece após duas correções: Pare de aplicar patches, volte ao manual e releia a seção relevante por completo, questionando seu próprio entendimento, em vez de continuar adivinhando.
• Conflito entre manual e convenção online: Siga o manual; não altere código que "funciona, mas não segue o manual" para a versão online, nem vice-versa.
• Erro: primeiro consulte o manual: Procure por códigos de erro, restrições, seções de condições limite; se o manual não tiver entrada correspondente, verifique evidências do ambiente; é proibido corrigir por intuição.
• Cada modificação: Adicione uma linha ao histórico de alterações em .rtfm/notes.md: objetivo, o que foi alterado, fonte. Se após duas rodadas ainda estiver errado, primeiro compare o histórico para evitar repetição.