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.
Ler instruções locais, PROJECT.md, .specsfy/STACK.md,
.specsfy/RULES.md, .specsfy/DATABASE.md, manifests, lockfiles,
metadados instalados e código existente.
Ler o padrão documental antes de
alterar a topologia publicada.
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>
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.
Executar --check para provar que a documentação representa o estado atual:
node scripts/build_documentation.mjs --project <raiz> --check
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.
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 documentar arquivos ignorados pelo Git. Dentro de um repositório, o script
lê somente arquivos rastreados ou não ignorados pelo
.gitignore; fora dele,
usa a lista fixa de pastas geradas.
- 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.
1---2name: specsfy-documentator-23description: Construir a documentação técnica em docs/ e o inventário npm/Composer em .specsfy/PACKAGES.md. Use ao documentar sistemas ou após implementações.4metadata:5 source: https://skillmd.com/skills/promovaweb/specsfy-documentator-26---78# Documentar o sistema910## Preparação obrigatória1112Antes de executar esta skill, carregue obrigatoriamente `$specsfy-setup` na13raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa.14Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma15pendência.1617## Modo de interação1819Modo de interação: `sem perguntas`.20Não formule perguntas nesta skill. Registre como não identificado todo dado21que as fontes executáveis não sustentarem.22231. Ler instruções locais, `PROJECT.md`, `.specsfy/STACK.md`,24 `.specsfy/RULES.md`, `.specsfy/DATABASE.md`, manifests, lockfiles,25 metadados instalados e código existente.262. Ler [o padrão documental](references/documentation-standard.md) antes de27 alterar a topologia publicada.283. Construir toda a documentação e `.specsfy/PACKAGES.md`, mesmo quando a29 skill for acionada sem uma spec ou implementação recente:3031 ```bash32 node scripts/build_documentation.mjs --project <raiz>33 ```34354. Inspecionar os arquivos gerados e corrigir manualmente somente inferências36 que o código não sustente. Não inventar decisões, relações ou integrações.375. Executar `--check` para provar que a documentação representa o estado atual:3839 ```bash40 node scripts/build_documentation.mjs --project <raiz> --check41 ```42436. Preservar conteúdo humano fora dos blocos `specsfy:documentator`, inclusive44 em `.specsfy/PACKAGES.md`. Tratar o bloco como projeção reconstruível das45 fontes locais.467. Registrar na evidência da tarefa o comando, resultado e arquivos atualizados.4748## Cobertura obrigatória4950Manter em `docs/`:5152- portal e roteiro de leitura;53- arquitetura, componentes e UML em Mermaid;54- inventário da aplicação e implementações existentes;55- banco e entidades com `erDiagram`;56- fluxos com `flowchart` e `sequenceDiagram`;57- guia e resumo dos testes;58- frontend, views, React e Tailwind;59- bibliotecas e pacotes nativos, de framework, integrados e terceiros, com60 versão, fonte e referência GitHub;61- integrações e variáveis de configuração sem valores sensíveis;62- decisões explícitas e suas fontes.6364Manter em `.specsfy/PACKAGES.md`:6566- todos os pacotes npm e Composer encontrados nos manifests e lockfiles do67 projeto, inclusive dependências transitivas registradas localmente;68- gerenciador, escopo, nome, versão, finalidade curta e fonte de cada pacote;69- descrição declarada no lockfile ou pacote instalado quando existir;70- aviso explícito quando os metadados locais não comprovarem a finalidade.7172Para Laravel, mapear rotas, controllers, models, services, jobs, policies,73Blade, migrations e Pest/PHPUnit. Para Node, Next.js, React ou Astro, mapear74páginas, rotas de API, componentes, módulos, scripts e Vitest/Jest/Node Test.7576## Limites7778- Não copiar segredos, valores de `.env`, dados de produção ou código inteiro.79- Não documentar arquivos ignorados pelo Git. Dentro de um repositório, o script80 lê somente arquivos rastreados ou não ignorados pelo `.gitignore`; fora dele,81 usa a lista fixa de pastas geradas.82- Não apresentar heurística como decisão confirmada.83- Não substituir specs, `PROJECT.md` ou arquivos humanos em `.specsfy/`.84 `PACKAGES.md` é a única projeção reconstruída pela skill nesse diretório e85 preserva conteúdo fora do bloco gerado.86- Não exigir rede para construir. Quando o repositório GitHub de um pacote não87 estiver declarado localmente nem for conhecido, publicar uma busca GitHub88 claramente rotulada, em vez de inventar uma URL.