name: api-documentador-revisor description: Revisa documentação de APIs gerada pela skill api-documentador, validando completude, consistência e qualidade por camada.

🔍 Revisor de Documentação de APIs

Skill para validação de documentação de APIs gerada pela skill api-documentador.

Referência: Skill api-documentador

[!IMPORTANT] Filosofia Core: Documentação de API é um produto. Se o público-alvo não encontra o que precisa rapidamente, a documentação falhou — independente de quão completa ela seja tecnicamente.

📋 Quando Usar

Execute esta skill quando:

• Após a skill api-documentador gerar a documentação
• Para validar que a documentação segue as regras propostas
• Quando o usuário pedir revisão de documentação de API existente

🎯 Instruções de Execução

1. Coletar Informações

Identifique:

1. O(s) documento(s) a serem revisados (diretório ./doc-apis/{titulo}/)
2. O tipo de documentação gerado (tecnica, nao-tecnica ou ambas)
3. A versão da revisão — verificar se já existem revisões anteriores para incrementar

2. Análise de Completude por Camada

Verifique se todas as camadas do tipo escolhido estão presentes e preenchidas.

Para tipo nao-tecnica

Para tipo tecnica

Para tipo ambas

• Todos os itens de nao-tecnica ✅
• Todos os itens de tecnica ✅
• Consistência entre camadas ✅
• Particionamento coerente ✅

3. Análise de Qualidade — Getting Started

Verificar:

• ✅ Linguagem de negócio (sem jargão técnico)
• ✅ Qualquer pessoa entende o que a API faz
• ✅ Tutorial claro de primeiros passos
• ✅ Responde: "O que é isso e como começo?"
• ❌ Jargão técnico (status codes, schemas, headers)
• ❌ Informação que só dev entende
• ❌ Ausência de tutorial prático

4. Análise de Qualidade — Casos de Uso

Verificar:

• ✅ Orientação por tarefa ("Como criar um pedido")
• ✅ Passo a passo visual e claro
• ✅ Problemas comuns com soluções práticas
• ✅ Glossário com termos traduzidos
• ✅ Fluxogramas visuais (quando aplicável)
• ❌ Orientação por endpoint (POST /orders)
• ❌ Erros listados sem solução
• ❌ Linguagem técnica no contexto de caso de uso

5. Análise de Qualidade — Referência Técnica

Verificar:

• ✅ Endpoints completos (método, path, params, body, responses)
• ✅ Schemas com tipos, constraints e enums
• ✅ Exemplos com valores reais (não placeholders genéricos)
• ✅ Autenticação clara com exemplos
• ✅ Formato padrão de erro definido
• ❌ Endpoints sem exemplos de response
• ❌ Schemas incompletos (faltando tipos ou constraints)
• ❌ Exemplos com valores genéricos ("string", "value")
• ❌ Ausência de cenários de erro

6. Análise de Qualidade — Suporte

Verificar:

• ✅ FAQ com perguntas reais (não inventadas)
• ✅ Ambientes documentados com URLs
• ✅ Template de abertura de chamado
• ❌ FAQ vazio ou com perguntas óbvias
• ❌ Ausência de informações de contato/escalar

7. Análise de Consistência

Verificar entre documentos (quando particionado):

• ✅ Endpoints citados nos casos de uso existem na referência técnica
• ✅ Erros nos casos de uso batem com os da referência técnica
• ✅ Termos do glossário cobrem o vocabulário usado nos documentos técnicos
• ✅ Ambientes são os mesmos em todas as camadas
• ❌ Endpoint mencionado no caso de uso que não existe na referência
• ❌ Dados divergentes entre camadas (URLs, limites, comportamentos)

8. Análise de Particionamento

Verificar (quando múltiplos documentos):

• ✅ Cada documento tem escopo coeso e bem delimitado
• ✅ Naming segue o padrão {titulo}-{contexto}-{dominio}.md
• ✅ Não há sobreposição significativa entre documentos
• ✅ Não há lacunas (endpoints ou fluxos não cobertos)
• ❌ Documento com escopo vago ou misturando domínios
• ❌ Informação duplicada entre documentos
• ❌ Informação perdida que deveria estar em algum documento

Verificar index.md:

• ✅ Arquivo index.md existe na raiz do diretório
• ✅ Todos os documentos de conteúdo estão listados com links relativos
• ✅ Documentos agrupados por camada (Getting Started, Casos de Uso, Ref. Técnica, Suporte)
• ✅ Cada documento com descrição breve
• ✅ Mapa de navegação por persona presente
• ✅ Apenas camadas do tipo escolhido estão presentes (sem seções vazias)
• ❌ Documentos de revisão (*-revision-*.md) incluídos no índice
• ❌ Links quebrados ou apontando para documentos inexistentes
• ❌ Ausência de index.md

9. Análise de Exemplos

Verificar:

• ✅ Exemplos com valores realistas e coerentes
• ✅ JSONs válidos e formatados
• ✅ UUIDs, datas, emails com formato correto
• ✅ Exemplos de erro com trace_id e códigos de negócio
• ❌ Valores genéricos ("string", "value", "xxx")
• ❌ JSONs inválidos ou mal formatados
• ❌ Exemplos que contradizem o schema

📝 Formato do Relatório

Gere o relatório em ./doc-apis/{titulo}/{titulo}-revision-{versao}.md:

# Relatório de Revisão — {titulo}

**Documentação:** {titulo}
**Tipo:** {tecnica / nao-tecnica / ambas}
**Versão da Revisão:** v{N}
**Data:** {YYYY-MM-DD}

## Resumo

| Categoria | Status | Problemas |
|---|---|---|
| Completude por Camada | ✅/⚠️/❌ | X |
| Getting Started | ✅/⚠️/❌ | X |
| Casos de Uso | ✅/⚠️/❌ | X |
| Referência Técnica | ✅/⚠️/❌ | X |
| Suporte | ✅/⚠️/❌ | X |
| Consistência | ✅/⚠️/❌ | X |
| Particionamento | ✅/⚠️/❌ | X |
| Índice (`index.md`) | ✅/⚠️/❌ | X |
| Exemplos | ✅/⚠️/❌ | X |

## Veredicto: ✅ APROVADO / ⚠️ AJUSTAR / ❌ REESCREVER

## Problemas Encontrados

### [Categoria]

#### [Problema 1]
- **Documento:** {arquivo.md}
- **Trecho:** "[trecho do documento]"
- **Problema:** [descrição objetiva]
- **Sugestão:** [como corrigir]

## Pontos Fortes

- [O que a documentação faz bem — reforço positivo]

## Recomendações Gerais

- [Lista de melhorias sugeridas, priorizadas por impacto]

⚠️ Observações

• Não reescreva a documentação. Aponte problemas e sugira direções — o autor deve reescrever.
• Adapte ao tipo: Se o tipo é tecnica, não cobre camadas de nao-tecnica (e vice-versa).
• Pragmatismo: Uma documentação não precisa ser perfeita, precisa ser útil para o público-alvo.
• Reforce o positivo: Sempre destaque o que a documentação faz bem antes de listar problemas.
• Priorize impacto: Foque em problemas que afetam a experiência do leitor, não em detalhes cosméticos.

⚡ Quick Reference

┌─────────────────────────────────────────────────────────────┐
│       REVISÃO DE DOC API — DECISÃO RÁPIDA                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Completude → Todas as camadas do tipo estão presentes?     │
│  Getting Started → Linguagem de negócio, sem jargão?        │
│  Casos de Uso → Orientação por tarefa, não por endpoint?    │
│  Ref. Técnica → Endpoints completos com exemplos reais?     │
│  Suporte → FAQ real, ambientes, template de chamado?        │
│  Consistência → Dados batem entre camadas/documentos?       │
│  Partição → Escopo coeso, sem sobreposição nem lacuna?      │
│  Exemplos → Valores reais, JSONs válidos?                   │
│                                                              │
│  TESTE: "O público-alvo encontra o que precisa?"            │
│         Se sim → ✅  Se não → ❌                              │
└─────────────────────────────────────────────────────────────┘

📚 Referências

• Skill api-documentador — Padrão de produção de documentação de APIs

💡 Lembre-se: Um bom revisor não busca perfeição — busca utilidade. Se o público-alvo consegue usar a documentação para resolver seus problemas, ela cumpriu seu papel.