@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-documentacao-tecnica/resources/checklists/documentation-validation.md

@@ -0,0 +1,296 @@
+# ✅ Checklist de Validação de Documentação Técnica
+
+## 📊 Score de Qualidade Automatizado
+
+### Cálculo do Score
+```
+Score Total = Completude (25) + Clareza (20) + Exemplos (20) + Atualização (15) + Formatação (10) + Links (10)
+Mínimo para avanço: 75/100 pontos
+```
+
+---
+
+## 🎯 Seção 1: Completude (25 pontos)
+
+### 📋 README.md (10 pontos)
+- [ ] **Título e Descrição** claros e impactantes (2 pts)
+- [ ] **Sumário** com links para seções principais (1 pt)
+- [ ] **Getting Started** completo com instalação (2 pts)
+- [ ] **Stack Tecnológica** detalhada (1 pt)
+- [ ] **Estrutura do Projeto** com diretórios (1 pt)
+- [ ] **Scripts Disponíveis** documentados (1 pt)
+- [ ] **Variáveis de Ambiente** explicadas (1 pt)
+- [ ] **Links Úteis** para documentação adicional (1 pt)
+
+### 📡 API Documentation (10 pontos)
+- [ ] **Autenticação** claramente documentada (2 pts)
+- [ ] **Endpoints** com método e descrição (2 pts)
+- [ ] **Request/Response** examples funcionais (2 pts)
+- [ ] **Error Handling** com códigos e exemplos (2 pts)
+- [ ] **Data Models** documentados (1 pt)
+- [ ] **Rate Limiting** e limites explicados (1 pt)
+
+### 📚 Documentação Adicional (5 pontos)
+- [ ] **Architecture Decision Records** para decisões importantes (2 pts)
+- [ ] **Contributing Guide** para desenvolvedores (1 pt)
+- [ ] **Troubleshooting Guide** com problemas comuns (1 pt)
+- [ ] **Changelog** com histórico de alterações (1 pt)
+
+---
+
+## 🔍 Seção 2: Clareza (20 pontos)
+
+### 📝 Linguagem e Escrita (10 pontos)
+- [ ] **Linguagem clara** e objetiva (2 pts)
+- [ ] **Público-alvo** definido e abordado (2 pts)
+- [ ] **Técnico vs Leigo** equilíbrio adequado (2 pts)
+- [ ] **Consistência** em terminologia (1 pt)
+- [ ] **Gramática e ortografia** sem erros (1 pt)
+- [ ] **Estrutura lógica** do conteúdo (1 pt)
+- [ ] **Títulos e subtítulos** informativos (1 pt)
+
+### 🎯 Foco e Relevância (10 pontos)
+- [ ] **Informação essencial** em destaque (2 pts)
+- [ ] **Detalhes irrelevantes** omitidos (2 pts)
+- [ ] **Contexto adequado** para cada seção (2 pts)
+- [ ] **Exemplos relevantes** para o público (2 pts)
+- [ ] **Priorização clara** de informações (1 pt)
+- [ ] **Escopo definido** e respeitado (1 pt)
+
+---
+
+## 💡 Seção 3: Exemplos Práticos (20 pontos)
+
+### 🔧 Exemplos de Código (10 pontos)
+- [ ] **Código funcional** e testado (3 pts)
+- [ ] **Sintaxe destacada** corretamente (2 pts)
+- [ ] **Comentários explicativos** no código (2 pts)
+- [ ] **Exemplos completos** (copy-paste funcionar) (2 pts)
+- [ ] **Múltiplos cenários** cobertos (1 pt)
+
+### 🌐 Exemplos de Uso (10 pontos)
+- [ ] **Comandos curl/testados** para APIs (3 pts)
+- [ ] **Exemplos de configuração** funcionais (2 pts)
+- [ ] **Fluxos completos** demonstrados (2 pts)
+- [ ] **Casos de borda** abordados (1 pt)
+- [ ] **Resultados esperados** mostrados (1 pt)
+- [ ] **Passo a passo** claro (1 pt)
+
+---
+
+## 🔄 Seção 4: Atualização (15 pontos)
+
+### 📅 Sincronização com Código (10 pontos)
+- [ ] **API endpoints** correspondem ao código atual (3 pts)
+- [ ] **Estrutura de projeto** reflete realidade (2 pts)
+- [ ] **Dependências** atualizadas no README (2 pts)
+- [ ] **Variáveis de ambiente** corretas (1 pt)
+- [ ] **Scripts** funcionais e atualizados (1 pt)
+- [ ] **Versões** de ferramentas corretas (1 pt)
+
+### 📈 Manutenção Contínua (5 pontos)
+- [ ] **Data de última atualização** visível (1 pt)
+- [ ] **Changelog** mantido atualizado (1 pt)
+- [ ] **Breaking changes** destacados (1 pt)
+- [ ] **Features deprecated** sinalizadas (1 pt)
+- [ ] **Contato para atualizações** disponível (1 pt)
+
+---
+
+## 🎨 Seção 5: Formatação (10 pontos)
+
+### 📄 Markdown e Estrutura (6 pontos)
+- [ ] **Markdown válido** e bem formatado (2 pts)
+- [ ] **Títulos hierárquicos** consistentes (1 pt)
+- [ ] **Listas e tabelas** bem formatadas (1 pt)
+- [ ] **Código blocks** com linguagem destacada (1 pt)
+- [ ] **Imagens e diagramas** legíveis (1 pt)
+
+### 🔗 Links e Referências (4 pontos)
+- [ ] **Links internos** funcionando (1 pt)
+- [ ] **Links externos** acessíveis (1 pt)
+- [ ] **Âncoras** para seções funcionando (1 pt)
+- [ ] **Referências cruzadas** adequadas (1 pt)
+
+---
+
+## 🔍 Seção 6: Links e Recursos (10 pontos)
+
+### 🌐 Links Externos (5 pontos)
+- [ ] **Documentação oficial** linkada (1 pt)
+- [ ] **Repositório** acessível (1 pt)
+- [ ] **Tutoriais e guias** relevantes (1 pt)
+- [ ] **Ferramentas recomendadas** com links (1 pt)
+- [ ] **Comunidade e suporte** disponível (1 pt)
+
+### 📚 Recursos Internos (5 pontos)
+- [ ] **Documentação relacionada** linkada (1 pt)
+- [ ] **Arquivos de configuração** referenciados (1 pt)
+- [ ] **Scripts e automações** documentados (1 pt)
+- [ ] **Diagramas e imagens** incluídos (1 pt)
+- [ ] **Exemplos e templates** disponíveis (1 pt)
+
+---
+
+## 🚀 Validação Automática
+
+### Scripts de Verificação
+
+#### 1. Verificação de Links
+```bash
+# Verifica links quebrados
+npm run check:links
+
+# Output esperado:
+✅ Internal links: 45/45 valid
+✅ External links: 23/23 valid
+❌ Broken links: 0 found
+```
+
+#### 2. Validação de Markdown
+```bash
+# Valida sintaxe markdown
+npm run validate:markdown
+
+# Output esperado:
+✅ Markdown syntax: Valid
+✅ Table formatting: Correct
+✅ Code blocks: Properly formatted
+```
+
+#### 3. Verificação de Exemplos
+```bash
+# Testa exemplos de código
+npm run test:examples
+
+# Output esperado:
+✅ Code examples: 12/12 working
+✅ API examples: 8/8 valid responses
+✅ Configuration examples: 5/5 valid
+```
+
+#### 4. Sincronização com Código
+```bash
+# Compara documentação com código
+npm run sync:check
+
+# Output esperado:
+✅ API endpoints: 15/15 synchronized
+✅ Database schema: Up to date
+✅ Environment variables: 8/8 correct
+```
+
+---
+
+## 📊 Relatório de Validação
+
+### Template de Relatório
+```markdown
+# 📊 Relatório de Validação - [Nome do Projeto]
+
+**Data:** [DD/MM/YYYY]  
+**Validador:** [Nome]  
+**Score Total:** [XX]/100 pontos  
+**Status:** [✅ Aprovado | 🔄 Revisão Necessária | ❌ Reprovado]
+
+## 🎯 Resultados por Seção
+
+| Seção | Pontos | Status | Observações |
+|-------|--------|--------|-------------|
+| Completude | [XX]/25 | [✅/⚠️/❌] | [Detalhes] |
+| Clareza | [XX]/20 | [✅/⚠️/❌] | [Detalhes] |
+| Exemplos | [XX]/20 | [✅/⚠️/❌] | [Detalhes] |
+| Atualização | [XX]/15 | [✅/⚠️/❌] | [Detalhes] |
+| Formatação | [XX]/10 | [✅/⚠️/❌] | [Detalhes] |
+| Links | [XX]/10 | [✅/⚠️/❌] | [Detalhes] |
+
+## ⚠️ Itens Pendentes
+
+### Críticos (Bloqueiam avanço)
+- [ ] [Item crítico 1]
+- [ ] [Item crítico 2]
+
+### Importantes (Recomendados)
+- [ ] [Item importante 1]
+- [ ] [Item importante 2]
+
+### Opcionais (Melhorias)
+- [ ] [Item opcional 1]
+- [ ] [Item opcional 2]
+
+## 🚀 Próximos Passos
+
+1. **Corrigir itens críticos** imediatamente
+2. **Implementar melhorias** importantes
+3. **Revalidar** após correções
+4. **Publicar** quando score ≥ 75
+
+## 📈 Métricas de Qualidade
+
+- **Tempo de leitura:** [X] minutos
+- **Complexidade técnica:** [Baixa|Média|Alta]
+- **Público-alvo:** [Desenvolvedores|Usuários|Ambos]
+- **Nível de detalhe:** [Adequado|Insuficiente|Excessivo]
+```
+
+---
+
+## 🔄 Processo de Validação
+
+### 1. Auto-Validação (Automática)
+```bash
+# Executa todas as validações
+npm run validate:docs
+
+# Gera relatório completo
+npm run validate:docs -- --report
+```
+
+### 2. Revisão Manual (Humana)
+- **Tech Lead:** Revisão técnica (30 min)
+- **Product Manager:** Revisão de conteúdo (20 min)
+- **UX Writer:** Revisão de clareza (15 min)
+
+### 3. Validação de Usuário
+- **Teste com usuário real:** 15 minutos
+- **Feedback coletado:** Formulário structured
+- **Métricas de satisfação:** NPS ≥ 8
+
+---
+
+## 🎯 Critérios de Aprovação
+
+### ✅ Aprovado (Score ≥ 75)
+- Publicação automática liberada
+- Deploy para produção autorizado
+- Documentação considerada "production-ready"
+
+### 🔄 Revisão Necessária (Score 60-74)
+- Correções obrigatórias necessárias
+- Revalidação após correções
+- Publicação bloqueada até aprovação
+
+### ❌ Reprovado (Score < 60)
+- Reestruturação completa necessária
+- Revisão profunda requerida
+- Novo ciclo de validação
+
+---
+
+## 📞 Contato e Suporte
+
+### Equipe de Validação
+- **Tech Lead:** [Nome] (email@company.com)
+- **Documentation Specialist:** [Nome] (email@company.com)
+- **QA Engineer:** [Nome] (email@company.com)
+
+### Canais de Comunicação
+- **Slack:** #documentation-review
+- **Discord:** #docs-validation
+- **Issues:** [GitHub Issues Link]
+
+---
+
+**Última atualização:** [DD/MM/YYYY]  
+**Versão do checklist:** v2.1  
+**Próxima revisão:** [DD/MM/YYYY]