--- 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:** ```regex 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: ```markdown # 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 1. Identificar arquivos a validar (glob `UC-*.md`) 2. Para cada arquivo: - Verificar estrutura - Validar conteúdo - Checar consistência - Testar diagramas 3. Gerar relatório consolidado 4. 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):** ``` plugins/cstk/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):** ``` plugins/cstk/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: ```yaml --- 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): 1. **Descricao** — 2-5 paragrafos explicando quando rodar 2. **Pre-requisitos** — checklist de itens necessarios 3. **Procedimento** — passos numerados com comandos literais 4. **Verificacao / Validacao** — como saber se o RB rodou OK 5. **Rollback** — passos reversos (OBRIGATORIO se `severidade=critica`) 6. **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`, ``, `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//spec.md`) contra os criterios ja documentados na skill `specify`. Motor deterministico: `plugins/cstk/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//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 de performance de implementacao (ex.: `TPS`, `paint time`, `render time`). Termos genericos de dominio (`API`, `CLI`, `JSON`) NAO disparam. | | `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//{plan,research,data-model,quickstart}.md` ou `docs/specs//contracts/*.md`. **Flag `--spec SPEC_MD`**: caminho explicito da `spec.md` correspondente, usado pelo check `dangling-fr-sc-ref`. Default: `/spec.md` resolvido pela convencao `docs/specs//` — **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 1. **Flag explicita** (`--sdd-spec`/`--sdd-plan`/`--runbook`) vence tudo. 2. **Deteccao automatica por path**: `UC-*.md` → perfil UC; `RB-\d{3}-*.md` → `--runbook`; `docs/specs//spec.md` → spec-profile; `docs/specs//{plan,research,data-model,quickstart}.md` ou `docs/specs//contracts/*.md` → plan-profile. 3. **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): ```console $ 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// 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.