specsfy-documentator

Documentar o sistema

Preparação obrigatória

Antes de executar esta skill, carregue obrigatoriamente $specsfy-setup na raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa. Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma pendência.

Modo de interação

Modo de interação: sem perguntas. Não formule perguntas nesta skill. Registre como não identificado todo dado que as fontes executáveis não sustentarem.

1. Ler instruções locais, PROJECT.md, .specsfy/STACK.md, .specsfy/RULES.md, .specsfy/DATABASE.md, manifests, lockfiles, metadados instalados e código existente.

2. Ler o padrão documental antes de alterar a topologia publicada.

3. Construir toda a documentação e .specsfy/PACKAGES.md, mesmo quando a skill for acionada sem uma spec ou implementação recente:

   node scripts/build_documentation.mjs --project <raiz>

4. Inspecionar os arquivos gerados e corrigir manualmente somente inferências que o código não sustente. Não inventar decisões, relações ou integrações.

5. Executar --check para provar que a documentação representa o estado atual:

   node scripts/build_documentation.mjs --project <raiz> --check

6. Preservar conteúdo humano fora dos blocos specsfy:documentator, inclusive em .specsfy/PACKAGES.md. Tratar o bloco como projeção reconstruível das fontes locais.

7. Registrar na evidência da tarefa o comando, resultado e arquivos atualizados.

Cobertura obrigatória

Manter em docs/:

• portal e roteiro de leitura;
• arquitetura, componentes e UML em Mermaid;
• inventário da aplicação e implementações existentes;
• banco e entidades com erDiagram;
• fluxos com flowchart e sequenceDiagram;
• guia e resumo dos testes;
• frontend, views, React e Tailwind;
• bibliotecas e pacotes nativos, de framework, integrados e terceiros, com versão, fonte e referência GitHub;
• integrações e variáveis de configuração sem valores sensíveis;
• decisões explícitas e suas fontes.

Manter em .specsfy/PACKAGES.md:

• todos os pacotes npm e Composer encontrados nos manifests e lockfiles do projeto, inclusive dependências transitivas registradas localmente;
• gerenciador, escopo, nome, versão, finalidade curta e fonte de cada pacote;
• descrição declarada no lockfile ou pacote instalado quando existir;
• aviso explícito quando os metadados locais não comprovarem a finalidade.

Para Laravel, mapear rotas, controllers, models, services, jobs, policies, Blade, migrations e Pest/PHPUnit. Para Node, Next.js, React ou Astro, mapear páginas, rotas de API, componentes, módulos, scripts e Vitest/Jest/Node Test.

Limites

• Não copiar segredos, valores de .env, dados de produção ou código inteiro.
• Não apresentar heurística como decisão confirmada.
• Não substituir specs, PROJECT.md ou arquivos humanos em .specsfy/. PACKAGES.md é a única projeção reconstruída pela skill nesse diretório e preserva conteúdo fora do bloco gerado.
• Não exigir rede para construir. Quando o repositório GitHub de um pacote não estiver declarado localmente nem for conhecido, publicar uma busca GitHub claramente rotulada, em vez de inventar uma URL.