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.

1. Ler [o padrão documental](references/documentation-standard.md) antes de

alterar a topologia publicada.

1. Construir toda a documentação e .specsfy/PACKAGES.md, mesmo quando a

skill for acionada sem uma spec ou implementação recente:

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

1. 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.

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

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

1. 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.

1. 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.