Documentar o sistema
- Ler instruções locais,
PROJECT.md, .specsfy/STACK.md,
.specsfy/RULES.md, .specsfy/DATABASE.md, manifests e código existente.
- Ler o padrão documental antes de
alterar a topologia publicada.
- Construir toda a documentação, mesmo quando a skill for acionada sem uma
spec ou implementação recente:
python3 -B scripts/build_documentation.py --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:
python3 -B scripts/build_documentation.py --project <raiz> --check
- Preservar conteúdo humano fora dos blocos
specsfy:documentator. Tratar o bloco como projeção reconstruível do código.
- Registrar na evidência da tarefa o comando, resultado e arquivos atualizados.
Cobertura obrigatória
Manter em docs/:
- portal e mapa 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.
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 .specsfy/; referenciá-los
como fontes.
- 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 ou reconstruir a documentação técnica completa de uma aplicação em docs/, a partir do código existente e das mudanças recém-implementadas. Use livremente quando o usuário pedir documentação, mapa técnico, arquitetura, UML, fluxos, banco, integrações, testes, frontend, Tailwind ou pacotes; use também obrigatoriamente depois de cada implementação conduzida por specsfy-07-implement. Funciona de forma independente, inclusive em projetos legados Laravel, Node, Next.js, React ou Astro, e preserva conteúdo humano fora dos blocos gerados.4---56# Documentar o sistema781. Ler instruções locais, `PROJECT.md`, `.specsfy/STACK.md`,9 `.specsfy/RULES.md`, `.specsfy/DATABASE.md`, manifests e código existente.102. Ler [o padrão documental](references/documentation-standard.md) antes de11 alterar a topologia publicada.123. Construir toda a documentação, mesmo quando a skill for acionada sem uma13 spec ou implementação recente:1415```bash16python3 -B scripts/build_documentation.py --project <raiz>17```18194. Inspecionar os arquivos gerados e corrigir manualmente somente inferências20 que o código não sustente. Não inventar decisões, relações ou integrações.215. Executar `--check` para provar que a documentação representa o estado atual:2223```bash24python3 -B scripts/build_documentation.py --project <raiz> --check25```26276. Preservar conteúdo humano fora dos blocos28 `specsfy:documentator`. Tratar o bloco como projeção reconstruível do código.297. Registrar na evidência da tarefa o comando, resultado e arquivos atualizados.3031## Cobertura obrigatória3233Manter em `docs/`:3435- portal e mapa de leitura;36- arquitetura, componentes e UML em Mermaid;37- inventário da aplicação e implementações existentes;38- banco e entidades com `erDiagram`;39- fluxos com `flowchart` e `sequenceDiagram`;40- guia e resumo dos testes;41- frontend, views, React e Tailwind;42- bibliotecas e pacotes nativos, de framework, integrados e terceiros, com43 versão, fonte e referência GitHub;44- integrações e variáveis de configuração sem valores sensíveis;45- decisões explícitas e suas fontes.4647Para Laravel, mapear rotas, controllers, models, services, jobs, policies,48Blade, migrations e Pest/PHPUnit. Para Node, Next.js, React ou Astro, mapear49páginas, rotas de API, componentes, módulos, scripts e Vitest/Jest/Node Test.5051## Limites5253- Não copiar segredos, valores de `.env`, dados de produção ou código inteiro.54- Não apresentar heurística como decisão confirmada.55- Não substituir specs, `PROJECT.md` ou arquivos `.specsfy/`; referenciá-los56 como fontes.57- Não exigir rede para construir. Quando o repositório GitHub de um pacote não58 estiver declarado localmente nem for conhecido, publicar uma busca GitHub59 claramente rotulada, em vez de inventar uma URL.
promovaweb