| name | documentation-project-scan |
| description | Executa uma varredura (scanner padrão) para descobrir artefatos documentais e lacunas no ecossistema `Documentation/` (ou equivalente) com base em padrões de nomes/pastas. Gera inventário/classificação e um backlog acionável. Raiz canónica `Documentation/`; incluir `Docs/` ou `docs/` legados na raiz até consolidarem. |
| model | sonnet |
| thinking | extended |
| category | documentation |
| license | MIT |
| copyright | Copyright (c) 2026 CSL Tech Solutions |
| company | CSL Tech Solutions |
| author | Claiton de Souza Linhares |
documentation-project-scan
Versão interna (ficheiro)
| Campo | Valor |
|---|
| FileVersion | 1.2.0 |
| Política | .cursor/VERSION.md |
Responsabilidade única
Esta skill executa uma varredura sistêmica do ecossistema documental do projeto — descobre artefatos existentes, classifica-os (canônico/superseded/duplicado/órfão) e gera um backlog acionável de lacunas. Cobre Documentation/, Analise/, Arquitetura/, Regras de Negocio/, Roadmap/ e pastas legadas. Não cria novos documentos nem faz scaffold de classes — essas responsabilidades pertencem a documentation-paste_analysis_unit_class_method; não migra nem consolida conteúdo — isso é documentation-migration-backup.
When to use
- Quando o usuário pedir "ver o que existe", "mapear documentos", "descobrir lacunas", "fazer inventário do acervo".
- Sempre que o ecossistema
Documentation/ for parcial/ausente ou quando existir risco de duplicação/caminhos divergentes.
Nota: a pasta Analise/ na raiz do repositório (análise por classe/interface) é inventariada aqui quando <escopo> incluir Analise/. A criação de ficheiros {ClassName}.md (tipos T… / I…) e da árvore de domínios é da skill documentation-paste_analysis_unit_class_method; este scan classifica e aponta lacunas, não substitui o scaffold.
Templates para resolver lacunas "criar": no backlog, quando a ação for criar um documento canónico, referenciar o TEMPLATE_* correspondente em .cursor/Templates/ (índice README.md).
When NOT to use
- Criar ou atualizar documentos individuais → usar
documentation-paste_analysis_unit_class_method (classes) ou documentation-business-rules, documentation-architecture conforme tipo.
- Migrar/consolidar documentação existente → usar
documentation-migration-backup.
- Gerar documentação de feature completa com análise de lacunas por módulo → usar
documentation-project-feature.
- Atualizar documentação após mudança de código → usar
documentation-project-update.
- Gerar índice de classes/interfaces para
Analise/ → usar documentation-analysis-index.
Inputs
<caminho_raiz> (opcional): diretório base do repositório (padrão: raiz do projeto).<versao_docs> (opcional): Vx.y para orientar critérios de naming.<escopo> (opcional): lista de pastas a varrer:
Documentation/, Docs/ ou docs/ (legado), Analise/, Arquitetura/, Regras de Negocio/, Esboco_Telas/, Roadmap/
<objetivo> (opcional): "scan para gaps" ou "scan para duplicação".
Dependências (skills prévias)
| Skill | Quando executar antes |
|---|
documentation-general_rules | Para confirmar naming conventions antes de classificar |
documentation-project-structure | Para mapear estrutura do repositório antes do scan |
Outputs obrigatórios
- Relatório de inventário (tabela):
- path
- categoria (hub/arquitetura/RN/telas/analise/versionamento/roadmap/openapi/etc.)
- versão (se houver)
- status (canônico/superseded/duplicado/transitório/órfão)
- evidência (frase/cabeçalho que suporta a classificação)
- Lista de lacunas (backlog):
- documento esperado (path canônico)
- status atual (existente/parcial/ausente)
- ação sugerida (criar/revisar/consolidar/mover para Backup)
- critérios de aceite testáveis
- Lista de conflitos de destino:
- destino canônico → origens que competem
- Inventário de unidades de código (V1.2.0+) — base para o gate de coverage-plan do
documentation-master-orchestrator:
- path do arquivo-fonte
- linguagem
- classe/módulo principal
- declarado em manifesto de dependências? (sim/não)
DEPENDENCY_GAPS.md (V1.2.0+) — cruzamento imports vs manifesto, persistido em Documentation/Decisions/:
- dependências importadas no código sem entrada no manifesto
- sugestão de versão (quando inferível pelo lock file)
Passos executíveis
1) Scanner padrão (incorporar regra de busca do plano)
Buscar por:
- entradas técnicas:
README*, CHANGELOG*, CONTRIBUTING*, LICENSE*
- documentação:
Documentation/, Analise/, Arquitetura/, Regras*, Roadmap*
- API/integração:
openapi*, swagger*, rotas/contratos e exemplos
- execução/qualidade: scripts de build/test/deploy e runbooks
- UI/fluxos: wireframes, telas, forms/views, protótipos
- governança:
.cursor/rules, .claude, .vscode, ADRs (se houver)
2) Classificar e versionar
- Determinar categoria e versão:
_Vx.y no nome do arquivo quando existente- campos internos no corpo quando existirem (quando não, usar evidencia mínima e marcar incerteza)
2b) Verificação Analise/ (domínio vs pastas)
Quando <escopo> incluir Analise/:
- Listar pastas em
Analise/ que não correspondam a um domínio derivado de src/ (ou a redirect documentado) — classificar como legado / órfã no relatório.
- Listar domínios esperados (a partir do mapa de units ou do README raiz) sem subpasta correspondente — backlog
criar ou reestruturar.
- No ProvidersORM, a pasta canónica
Analise/Database/ cobre units Providers.Database.* e Providers.Databases.*; não deve existir paralelo Analise/Providers.Database/ ou Analise/Providers.Databases/ (removidos após fusão em Database/).
3) Derivar ações acionáveis
- Para cada artefato esperado do template:
- mapear para estado atual
- sugerir ação
criar vs revisar/consolidar vs "superseded → Backup"
- garantir critérios de aceite testáveis
4) Cruzamento dependências vs imports (V1.2.0+, stack-aware)
Para cada stack detectada no projeto, comparar imports do código com o manifesto de dependências:
| Stack | Manifesto de dependências | Fonte de imports |
|---|
| Python | requirements.txt, pyproject.toml, setup.py, Pipfile | import X / from X import em *.py |
| Node.js | package.json (dependencies + devDependencies) | require() / import em *.js/*.ts/*.jsx/*.tsx |
| Pascal (Delphi/FPC) | *.dpk / *.dproj (Requires), *.lpk / *.lpi (RequiredPackages) | cláusula uses em *.pas / *.dpr / *.lpr |
| Rust | Cargo.toml ([dependencies]) | use / extern crate em *.rs |
| Go | go.mod (require) | import em *.go |
| Java/Kotlin | pom.xml / build.gradle | import em *.java/*.kt |
Saída obrigatória: Documentation/Decisions/DEPENDENCY_GAPS.md listando:
- módulos importados mas ausentes do manifesto
- sugestão de versão (quando lock file disponível)
- evidência (arquivo + linha)
Nota: imports de stdlib/built-in não devem entrar como gap (manter lista de exclusão por stack).
Critérios de aceite da skill
- O relatório inclui todos os campos obrigatórios do output.
- Conflitos de destino são explicitamente listados (destino → origens).
- O backlog é acionável: cada item tem critérios de aceite (não genérico).
- V1.2.0+: Inventário de unidades de código produzido (base para gate de coverage-plan).
- V1.2.0+:
DEPENDENCY_GAPS.md gerado em Documentation/Decisions/ com cruzamento imports vs manifesto (vazio é resposta válida — significa "manifesto completo").
Regras transversais
- Usar skill
documentation-general_rules (naming conventions) para naming.
- Respeitar skill
documentation-general_rules (language policy) para idioma.
- Não inventar arquivos: se o scan não encontrar, classificar como ausente/parcial e listar no backlog.
Template de saída (relatório)
O relatório deve conter ao menos:
- Resumo executivo (3–6 bullets)
- Tabela inventário
- Backlog lacunas (tabela)
- Conflitos de destino (lista)
Exemplo de referência canônica
.cursor/Templates/README.md — mapa de TEMPLATE_* por tipo de artefacto.- "EXEMPLO DE DOCUMENTAÇÃO/Docs/…" (quando existir) como layout de referência.
Anti-padrões
| Anti-padrão | Por que é errado | Como corrigir |
|---|
| Inventar documentos que não foram encontrados no scan | Gera backlog falso e direciona esforço para trabalho inexistente | Classificar como ausente/parcial apenas o que o scan confirma; nunca criar entradas sem evidência |
| Usar este scan para criar ou scaffold de documentos | Mistura responsabilidades; cria arquivos sem estrutura correta | Usar documentation-paste_analysis_unit_class_method para criação; este scan apenas classifica |
| Não listar conflitos de destino quando há duplicação | Deixa ambiguidade sobre qual documento é canônico | Sempre gerar seção "Conflitos de destino" mesmo que vazia |
| Classificar documentos sem evidência no corpo | Rótulo arbitrário que muda a cada scan | Incluir evidência (citação do cabeçalho ou metadado) para cada classificação |
| Pular cruzamento de dependências vs imports (V1.2.0+) | Manifesto fica desalinhado do código real; build em outra máquina falha por dependência ausente | Sempre executar passo 4 e gerar DEPENDENCY_GAPS.md, mesmo se o resultado for vazio |
| Inventariar unidades de código sem registrar manifesto declarado (V1.2.0+) | Coverage-plan posterior fica cego à origem da dependência | Marcar cada unidade com flag declarado em manifesto? no inventário |
Métricas de sucesso
- O relatório de inventário cobre 100% das pastas no
<escopo> fornecido.
- Todo item do backlog tem critérios de aceite testáveis (não genérico).
- Conflitos de destino identificados no scan são todos explicitados na seção correspondente.
- Nenhum documento é inventariado sem evidência de classificação.
Responsável principal
| Papel | Quem |
|---|
| Executor | doc-agent-orchestrator |
| Revisão | documentation-general_rules |
Changelog (este arquivo)
- 1.2.0 (26/04/2026): Novo passo 4 — cruzamento dependências vs imports (stack-aware: Python, Node.js, Pascal, Rust, Go, Java/Kotlin); novo output inventário de unidades de código (base para gate de coverage-plan do
documentation-master-orchestrator V1.2.0); novo output DEPENDENCY_GAPS.md em Documentation/Decisions/; 2 novos critérios de aceite; 2 novos anti-padrões.
- 1.1.0 (09/04/2026): Migração V2 —
thinking: extended, category: documentation, Responsabilidade única, When NOT to use, Dependências, Anti-padrões, Métricas de sucesso, Responsável principal adicionados.
- 1.0.4 (28/03/2026): ProvidersORM — redirects
Analise/Providers.Database/ e Analise/Providers.Databases/ removidos; nota de scan actualizada.
- 1.0.3 (28/03/2026): Passo 2b — verificação de pastas
Analise/ vs domínios (órfãs, em falta; nota ProvidersORM Database/).
- 1.0.2 (27/03/2026): Lacunas "criar" — remeter a
.cursor/Templates/; exemplo de referência actualizado.
- 1.0.1 (27/03/2026): Nota
Analise/ — criação de {ClassName}.md (T… / I…) remete a documentation-paste_analysis_unit_class_method 1.2.0.
- 1.0.1 (30/03/2026): Rubrica de versionamento interno (política:
.cursor/VERSION.md).
- 1.0.0 (30/03/2026): Versionamento interno inicial (pacote
.cursor).
