| name | validate-documentation |
| description | Validate a single existing document's quality/completeness against structural standards. Triggers: "validar documentacao", "verificar UC", "audit docs". Skip for cross-artifact spec/plan/tasks consistency (use analyze). |
| allowed-tools | ["Read","Glob","Grep"] |
Skill: Validação de Documentação
Esta skill analisa e valida documentação existente contra padrões de qualidade.
Quando Usar
Claude deve invocar esta skill automaticamente quando:
- Usuário pedir para validar/verificar documentação
- Usuário mencionar "review", "audit" ou "checar" documentos
- Antes de finalizar criação de documentação (auto-validação)
- Usuário pedir status de qualidade da documentação
Critérios de Validação
1. Validação Estrutural (Documentos UC)
Seções Obrigatórias:
- [ ] Informações Gerais (tabela com ID, Nome, Domínio)
- [ ] Descrição (mínimo 2 parágrafos)
- [ ] Atores (tabela com tipo e descrição)
- [ ] Pré-condições (lista numerada)
- [ ] Pós-condições (sucesso e falha)
- [ ] Fluxo Principal (diagrama + tabela)
- [ ] Fluxos Alternativos (ao menos 1)
- [ ] Exceções (tabela com códigos)
- [ ] Regras de Negócio (tabela com IDs)
- [ ] Casos de Teste (tabela com cenários)
- [ ] Dependências (relacionamentos)
Padrões de ID:
UC-[A-Z]{2,4}-\d{3} # UC-CAD-001, UC-AUTH-001
RN\d{2} # RN01, RN02
CT\d{2} # CT01, CT02
E\d{3} # E001, E002
FA\d # FA1, FA2
RNF\d{2} # RNF01, RNF02
2. Validação de Conteúdo
Descrição:
- Mínimo 100 caracteres
- Deve explicar O QUE e POR QUE
Atores:
- Pelo menos 1 ator primário
- Tipo deve ser: Primário, Secundário ou Sistema
- Descrição deve ser clara
Fluxo Principal:
- Diagrama Mermaid deve ser válido
- Passos devem ser numerados sequencialmente
- Cada passo deve ter descrição clara
Regras de Negócio:
- Cada regra deve ser acionável
- Regras complexas devem ter detalhamento
Casos de Teste:
- Mínimo 5 casos por UC
- Deve cobrir: sucesso, erro, edge cases
- Cada caso deve ter entrada e saída esperada
3. Validação de Consistência
Cross-references:
- Dependências devem referenciar UCs existentes
- Links internos devem ser válidos
- IDs não devem ser duplicados
Nomenclatura:
- Campos devem seguir padrão (camelCase ou UPPER_CASE)
- Nomes de atores consistentes entre documentos
- Terminologia uniforme
4. Validação de Diagramas Mermaid
sequenceDiagram:
- Participantes definidos
- Mensagens com setas corretas (->>, -->>)
- Alt/else para fluxos condicionais
- Loop para repetições
flowchart:
- Nós com IDs únicos
- Conexões válidas
- Decisões com múltiplas saídas
Relatório de Validação
Formato do relatório gerado:
# Relatório de Validação de Documentação
**Data:** YYYY-MM-DD
**Arquivos analisados:** N
## Resumo
| Status | Quantidade |
|--------|------------|
| OK | X |
| Aviso | Y |
| Erro | Z |
## Detalhes por Arquivo
### UC-XXX-NNN.md
**Status:** OK | Aviso | Erro
**Validações:**
- [x] Estrutura completa
- [x] Conteúdo adequado
- [ ] Consistência - Falta detalhar RN03
- [x] Diagramas válidos
**Ações recomendadas:**
1. Adicionar detalhamento para RN03
2. Incluir mais casos de teste de erro
---
Níveis de Severidade
| Nível | Descrição | Ação |
|---|
| Erro | Seção obrigatória ausente | Bloqueia aprovação |
| Aviso | Conteúdo insuficiente | Recomenda correção |
| Info | Sugestão de melhoria | Opcional |
Processo de Validação
- Identificar arquivos a validar (glob
UC-*.md)
- Para cada arquivo:
- Verificar estrutura
- Validar conteúdo
- Checar consistência
- Testar diagramas
- Gerar relatório consolidado
- Sugerir correções específicas
Comandos de Validação
Validar um arquivo:
Valide o documento UC-CAD-001.md
Validar todos os UCs:
Valide toda a documentação de casos de uso
Validar com auto-correção:
Valide e corrija os problemas encontrados em UC-CAD-001.md
Validar runbook (perfil --runbook):
Valide o runbook RB-001-restore-drill.md com perfil --runbook
Validar spec.md de uma feature SDD (perfil spec-profile):
global/skills/validate-documentation/scripts/validate-sdd.sh docs/specs/minha-feature/spec.md
Validar plan.md de uma feature SDD (perfil plan-profile, com referencia cruzada de IDs):
global/skills/validate-documentation/scripts/validate-sdd.sh docs/specs/minha-feature/plan.md --spec docs/specs/minha-feature/spec.md
Perfil --runbook (RB-NNN)
Runbooks operacionais (docs/08-operacoes/RB-*.md) tem padrao
estrutural diferente de UCs e exigem perfil dedicado. Acionar via
flag --runbook ou quando o filename casa RB-\d{3}-*.md.
Frontmatter YAML obrigatorio
Todo runbook DEVE ter frontmatter YAML com pelo menos:
---
title: "RB-001: Restore Drill PostgreSQL"
versao: 1.0
severidade: critica
tempo-estimado: 45min
pre-requisitos:
- acesso-ssh-droplet-prod
- backup-recente-em-s3
---
Campos obrigatorios:
title casa regex ^RB-\d{3}: .+versao (semver ou inteiro)severidade (enum acima)tempo-estimado (string com unidade — min, h)pre-requisitos (array de strings)
Secoes obrigatorias
Cada runbook DEVE ter (na ordem):
- Descricao — 2-5 paragrafos explicando quando rodar
- Pre-requisitos — checklist de itens necessarios
- Procedimento — passos numerados com comandos literais
- Verificacao / Validacao — como saber se o RB rodou OK
- Rollback — passos reversos (OBRIGATORIO se
severidade=critica)
- Contatos — quem chamar em caso de problema
Ausencia de qualquer secao acima e Erro (nao Aviso). Para
severidade=critica sem secao Rollback, erro adicional CRITICO.
Checks adicionais
- Sem placeholders residuais: rejeitar se conteudo contem
TODO:/TODO(, XXX, FIXME, <placeholder>, lorem ipsum,
TBD, [FILL ME]. Runbook e operacional — placeholder e divida
tecnica que vira incidente. NOTA (corpus pt-br): exigir o marcador
DELIMITADO — TODO: (dois-pontos) ou TODO( (estilo comentario de
codigo) — e NAO o token solto TODO. Em prosa pt-br, "TODO/TODA" em
enfase CAIXA-ALTA (ex: "para TODO comando") e legitimo e NAO deve
disparar falso-positivo.
- Cross-refs validos: paths relativos em links Markdown
(
[texto](../path)) devem existir no disco. Reportar
link quebrado como Erro.
- Comandos sem variavel de ambiente nao-documentada: se
procedimento usa
$VAR, VAR deve estar listado em
Pre-requisitos OU em frontmatter env-vars: [...]. Caso
contrario, Aviso (operador pode esquecer de exportar).
Criterio de aceitacao
Novo RB-NNN e REJEITADO por validate-documentation --runbook se
faltar qualquer:
- Campo obrigatorio do frontmatter
- Secao obrigatoria
- Rollback (quando severidade=critica)
- Cross-ref valido em link interno
Razao para rigor extra: runbooks rodam em incidente, com operador
sob pressao. Placeholder = pessoa errada lendo o passo errado em
2h da manha.
Perfil spec-profile (SDD)
Valida spec.md de uma feature SDD (docs/specs/<feature>/spec.md)
contra os criterios ja documentados na skill specify. Motor
deterministico: global/skills/validate-documentation/scripts/validate-sdd.sh
(POSIX sh, mesmo padrao de create-tasks/scripts/validate-tasks-template.sh
e validate-docs-rendered/scripts/validate.sh).
Quando usar: apos specify (ou apos clarify), antes de avancar para
plan — gate de qualidade da spec antes de investir em desenho tecnico.
Acionamento: flag --sdd-spec (forca o perfil, ignora deteccao por
path) OU deteccao automatica quando FILE casa a convencao
docs/specs/<feature>/spec.md.
Catalogo de findings (spec-profile)
| code | severidade | Condicao |
|---|
missing-section | Erro | Falta uma das 3 secoes obrigatorias (User Scenarios & Testing, Requirements, Success Criteria). |
impl-detail-in-spec | Erro | Termo de stack/linguagem/framework/lib especifica no corpo da spec (ex.: bcrypt, PostgreSQL, React). |
sc-not-measurable | Erro | Success Criterion sem metrica quantificavel OU com jargao tecnico (ex.: API, TPS, paint time). |
too-many-clarifications | Erro | Mais de 3 marcadores [NEEDS CLARIFICATION] no total. |
duplicate-id | Erro | ID FR-/SC- repetido no mesmo documento (reusa a convencao do Gotcha abaixo). |
na-placeholder-section | Aviso | Secao deixada com placeholder N/A em vez de removida. |
vague-adjective | Aviso | Adjetivo vago sem quantificacao em Requirements/Success Criteria (ex.: "MUST be fast", "deve ser robusto"). |
coupled-user-story | Aviso | User story que depende de outra para ser testada isoladamente. |
Wordlists/regex de impl-detail-in-spec/sc-not-measurable/vague-adjective
sao calibradas contra os 6 anti-padroes de specify/examples/spec-bad.md
(deliberadamente restritas a termos concretos de stack — nao termos
genericos de dominio como "API"/"CLI"/"JSON" que aparecem legitimamente em
specs de ferramentas de dev, o que geraria falso-positivo).
Perfil plan-profile (SDD)
Valida os artefatos de /plan de uma feature SDD — plan.md,
research.md, data-model.md, quickstart.md, contracts/*.md — contra
os criterios ja documentados na skill plan. Mesmo motor
scripts/validate-sdd.sh.
Quando usar: apos plan, antes de checklist/create-tasks — gate de
qualidade do desenho tecnico.
Acionamento: flag --sdd-plan OU deteccao automatica quando FILE
casa docs/specs/<feature>/{plan,research,data-model,quickstart}.md ou
docs/specs/<feature>/contracts/*.md.
Flag --spec SPEC_MD: caminho explicito da spec.md correspondente,
usado pelo check dangling-fr-sc-ref. Default: <dir-de-FILE>/spec.md
resolvido pela convencao docs/specs/<feature>/ — so quando FILE
segue essa convencao. A flag explicita --spec aceita QUALQUER path
(inclusive fixtures de teste fora de docs/specs/); a restricao de
convencao se aplica somente ao default automatico.
Catalogo de findings (plan-profile)
| code | severidade | Escopo | Condicao |
|---|
missing-section | Erro | plan.md | Falta uma das 4 secoes obrigatorias (Summary, Technical Context, Constitution Check, Project Structure). |
template-placeholder | Erro | qualquer artefato /plan | Token de template nao preenchido ([FEATURE], [DATE], [short-name], [Topico], [Endpoint/Command/Event]). |
unlabeled-contract | Erro | contracts/*.md | Entrada que documenta um Command/Endpoint/Event sem rotulo inequivoco real-vs-proposto ([PROPOSTA — a validar na implementacao] ou [EXISTENTE]). |
residual-clarification | Erro | plan.md | [NEEDS CLARIFICATION] remanescente. |
dangling-fr-sc-ref | Erro | plan.md | ID FR-/SC- citado que NAO existe na spec.md correspondente — checagem SEMANTICA apenas, nunca resolucao de link/anchor no disco. |
Precedencia de selecao de perfil
- Flag explicita (
--sdd-spec/--sdd-plan/--runbook) vence tudo.
- Deteccao automatica por path:
UC-*.md → perfil UC; RB-\d{3}-*.md
→ --runbook; docs/specs/<feature>/spec.md → spec-profile;
docs/specs/<feature>/{plan,research,data-model,quickstart}.md ou
docs/specs/<feature>/contracts/*.md → plan-profile.
- Nem flag nem convencao reconhecida → perfil indeterminado, mensagem
clara em stderr, exit 2 — NUNCA aplica um perfil por engano.
Exemplos (espelham contracts/validate-sdd-cli.md §Exemplos de saida):
$ validate-sdd.sh docs/specs/enforced-guards/spec.md
RESULT|docs/specs/enforced-guards/spec.md|profile=spec|errors=0|warnings=0
# exit 0
$ validate-sdd.sh docs/specs/x/plan.md
FINDING|error|template-placeholder|Token de template nao preenchido: [FEATURE]
FINDING|error|dangling-fr-sc-ref|plan.md cita FR-099, ausente na spec.md correspondente
RESULT|docs/specs/x/plan.md|profile=plan|errors=2|warnings=0
# exit 1
$ validate-sdd.sh /tmp/qualquer/spec.md
Perfil nao determinado para '/tmp/qualquer/spec.md': path fora da convencao docs/specs/<feature>/ e nenhuma flag informada. Use --sdd-spec ou --sdd-plan.
# exit 2
Fronteira de nao-duplicacao (spec-profile/plan-profile vs analyze vs validate-docs-rendered)
Tres skills tocam artefatos SDD; cada categoria de check tem UM dono, sem
sobreposicao (SC-005 da feature validate-docs-sdd-profile):
| Categoria de check | Dono | spec/plan-profile faz? |
|---|
| Secoes obrigatorias presentes num UNICO artefato | validate-documentation (spec/plan-profile) | SIM |
Anti-padroes de conteudo da spec (impl. vazando, SC nao-mensuravel, [NEEDS CLARIFICATION] > 3, stories acopladas, adjetivos vagos, N/A residual) | validate-documentation (spec-profile) | SIM |
Placeholder de template residual / rotulo real-vs-proposto / [NEEDS CLARIFICATION] residual no plan | validate-documentation (plan-profile) | SIM |
ID FR-/SC- citado em plan.md EXISTE na spec.md (checagem SEMANTICA) | validate-documentation (plan-profile) | SIM |
| Link/anchor entre arquivos RESOLVE no disco (arquivo existe, header casa) | validate-docs-rendered | NAO |
| Sintaxe Mermaid, frontmatter YAML, code-block sem linguagem | validate-docs-rendered | NAO |
| Cobertura cross-artifact (tasks vs requisitos, duplicacao, gaps, drift de terminologia, alinhamento com constitution) | analyze | NAO |
| Drift de case-convention entre camadas (snake vs camel) | analyze (Pass G) | NAO |
A linha mais sutil e a de referencia cruzada de IDs: plan-profile faz
APENAS a checagem semantica (o ID existe na spec?), NUNCA a resolucao de
path/anchor no disco — essa fica 100% com validate-docs-rendered.
Gotchas
Valida DOCUMENTO INDIVIDUAL, nao relacionamento entre artefatos
Para verificar se o tasks.md cobre os requisitos do spec.md, ou se plan.md viola constitution.md, use a skill analyze. Esta skill valida UM documento contra padroes estruturais — UC tem todas as secoes, diagramas parseaveis, IDs nao-duplicados, etc.
Diagrama Mermaid com erro de sintaxe nao e cosmetico
Um sequenceDiagram sem participant declarado, ou setas fora do padrao (--> ao inves de ->>), quebra o render em GitHub/viewers. Sempre validar que o diagrama parseia — idealmente via script.
IDs duplicados dentro do mesmo documento sao erro, nao aviso
RN01 aparecendo duas vezes, ou CT03 com dois cenarios distintos, quebra rastreabilidade. Detectar e reportar como Erro, nao Aviso.
duplicate-id do spec-profile reusa esta convencao, nao inventa criterio novo
O check duplicate-id de spec-profile (perfil SDD, acima) aplica a MESMA
regra deste Gotcha a FR-/SC- em spec.md — nao ha FR proprio na spec
da feature validate-docs-sdd-profile cobrindo esse check porque ele reusa
uma convencao ja estabelecida aqui, e nao introduz criterio novo. Fecha
CHK004/CHK013 (checklist da feature): a citacao a este Gotcha, e nao a um
FR-NNN inexistente, e a rastreabilidade correta.
Minimo 5 casos de teste (sucesso + erro + edge) — abaixo disso reprova
UC com 2 CTs e incompleto. A cobertura minima e: 1-2 cenarios de sucesso + 1-2 de erro + 1 edge case. Menos que isso, o UC nao esta pronto para implementacao.
Auto-correcao pede confirmacao — nao aplicar direto
Mesmo quando o usuario pediu "valide e corrija", apresentar o que sera mudado antes de escrever. Correcao automatica em documento humano sem review gera desconfianca do sistema.
