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  # critica | alta | media | baixa
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.