@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-dados-analytics-ia/resources/templates/slo-sli.md

@@ -0,0 +1,381 @@
+# 📊 Service Level Objectives (SLOs) e Service Level Indicators (SLIs)
+
+## 📋 Metadados
+
+**Data de Criação:** [DD/MM/YYYY]  
+**Responsável:** [Nome do Analista]  
+**Versão:** 1.0  
+**Próxima Revisão:** [DD/MM/YYYY]  
+
+---
+
+## 🎯 Visão Geral
+
+### Objetivo
+Definir objetivos e indicadores de nível de serviço para garantir a qualidade, confiabilidade e performance dos pipelines de dados e dashboards analytics.
+
+### Escopo
+- **Pipelines de Dados**: ETL/ELT processes
+- **Data Warehouse**: Disponibilidade e performance
+- **Dashboards**: Tempo de carregamento e atualização
+- **Qualidade de Dados**: Precisão e completude
+
+---
+
+## 🎯 Service Level Objectives (SLOs)
+
+### 1. Disponibilidade do Pipeline
+
+#### SLO
+- **Objetivo:** 99.5% de disponibilidade mensal
+- **Período de medição:** 30 dias rolling
+- **Janela de erro:** 5 minutos
+
+#### SLIs
+| Indicador | Métrica | Target | Frequência |
+|-----------|---------|--------|------------|
+| **Pipeline Success Rate** | % de execuções bem-sucedidas | ≥ 99.5% | A cada execução |
+| **Pipeline Recovery Time** | Tempo para recuperação de falhas | ≤ 5 minutos | Após falha |
+| **Data Freshness** | Idade dos dados mais recentes | ≤ 30 minutos | A cada execução |
+
+#### Cálculo
+```sql
+-- Pipeline Success Rate
+SELECT 
+    COUNT(CASE WHEN status = 'success' THEN 1 END) * 100.0 / COUNT(*) as success_rate
+FROM pipeline_executions 
+WHERE execution_time >= NOW() - INTERVAL '30 days';
+```
+
+### 2. Performance do Data Warehouse
+
+#### SLO
+- **Objetivo:** 95% das queries executam em < 10 segundos
+- **Período de medição:** 7 dias rolling
+- **Janela de erro**: 99th percentile
+
+#### SLIs
+| Indicador | Métrica | Target | Frequência |
+|-----------|---------|--------|------------|
+| **Query Response Time** | Tempo de resposta das queries | ≤ 10s (P95) | A cada query |
+| **Concurrent Connections** | Conexões simultâneas suportadas | ≥ 100 | Contínuo |
+| **Warehouse Uptime** | Disponibilidade do warehouse | ≥ 99.9% | Contínuo |
+
+#### Cálculo
+```sql
+-- Query Response Time P95
+SELECT 
+    percentile_cont(0.95) WITHIN GROUP (ORDER BY execution_time_ms) as p95_response_time
+FROM query_log 
+WHERE query_time >= NOW() - INTERVAL '7 days';
+```
+
+### 3. Qualidade de Dados
+
+#### SLO
+- **Objetivo:** 95% dos dados passam em validações de qualidade
+- **Período de medição**: Diário
+- **Janela de erro**: Batch completo
+
+#### SLIs
+| Indicador | Métrica | Target | Frequência |
+|-----------|---------|--------|------------|
+| **Data Completeness** | % de registros não nulos | ≥ 98% | A cada batch |
+| **Data Accuracy** | % de dados corretos | ≥ 99% | Amostragem diária |
+| **Data Consistency** | % de dados consistentes | ≥ 99% | A cada batch |
+| **Schema Validation** | % de schemas válidos | 100% | A cada batch |
+
+#### Cálculo
+```sql
+-- Data Completeness
+SELECT 
+    table_name,
+    COUNT(CASE WHEN critical_field IS NOT NULL THEN 1 END) * 100.0 / COUNT(*) as completeness_rate
+FROM data_quality_metrics 
+WHERE validation_date = CURRENT_DATE
+GROUP BY table_name;
+```
+
+### 4. Performance de Dashboards
+
+#### SLO
+- **Objetivo:** 95% dos dashboards carregam em < 5 segundos
+- **Período de medição:** 24 horas
+- **Janela de erro**: P95
+
+#### SLIs
+| Indicador | Métrica | Target | Frequência |
+|-----------|---------|--------|------------|
+| **Dashboard Load Time** | Tempo de carregamento | ≤ 5s (P95) | A cada acesso |
+| **Data Refresh Time** | Tempo de atualização | ≤ 2 minutos | A cada refresh |
+| **Interactive Response** | Tempo de resposta a filtros | ≤ 1s | A cada interação |
+
+#### Cálculo
+```sql
+-- Dashboard Load Time P95
+SELECT 
+    dashboard_id,
+    percentile_cont(0.95) WITHIN GROUP (ORDER BY load_time_ms) as p95_load_time
+FROM dashboard_access_log 
+WHERE access_time >= NOW() - INTERVAL '24 hours'
+GROUP BY dashboard_id;
+```
+
+---
+
+## 📈 Monitoramento e Alertas
+
+### Configuração de Alertas
+
+#### Alertas Críticos
+```yaml
+alerts:
+  critical:
+    - name: "Pipeline Down"
+      condition: "pipeline_success_rate < 99.0"
+      severity: "critical"
+      notification: ["slack", "email", "pagerduty"]
+      
+    - name: "Data Quality Drop"
+      condition: "data_quality_score < 90.0"
+      severity: "critical"
+      notification: ["slack", "email"]
+      
+    - name: "Warehouse Unavailable"
+      condition: "warehouse_uptime < 99.5"
+      severity: "critical"
+      notification: ["slack", "email", "pagerduty"]
+
+  warning:
+    - name: "Slow Queries"
+      condition: "p95_query_time > 15s"
+      severity: "warning"
+      notification: ["slack"]
+      
+    - name: "Dashboard Slow"
+      condition: "p95_dashboard_load > 8s"
+      severity: "warning"
+      notification: ["slack"]
+```
+
+### Dashboard de SLOs
+
+#### Métricas Principais
+1. **Overall Health Score**: Média ponderada de todos os SLOs
+2. **Pipeline Status**: Status atual dos pipelines
+3. **Data Quality Trend**: Tendência de qualidade dos dados
+4. **Performance Metrics**: Tempos de resposta e throughput
+
+#### Visualizações
+```sql
+-- Overall Health Score
+WITH slo_metrics AS (
+  SELECT 
+    'pipeline_availability' as slo_name,
+    (pipeline_success_rate / 99.5) * 100 as score
+  FROM slo_metrics_current
+  UNION ALL
+  SELECT 
+    'query_performance' as slo_name,
+    (100 - (p95_query_time - 10) / 10 * 100) as score
+  FROM slo_metrics_current
+  UNION ALL
+  SELECT 
+    'data_quality' as slo_name,
+    data_quality_score
+  FROM slo_metrics_current
+)
+SELECT 
+    AVG(score) as overall_health_score,
+    COUNT(CASE WHEN score >= 100 THEN 1 END) as slos_met,
+    COUNT(*) as total_slos
+FROM slo_metrics;
+```
+
+---
+
+## 🔄 Processo de Gerenciamento
+
+### 1. Definição de SLOs
+
+#### Critérios para Definir SLOs
+- **Mensurável**: Pode ser medido objetivamente
+- **Atingível:** Realista com recursos atuais
+- **Relevante**: Importante para o negócio
+- **Temporal**: Com prazo definido
+
+#### Processo
+1. **Identificar serviços críticos**
+2. **Definir indicadores de qualidade**
+3. **Estabelecer metas realistas**
+4. **Configurar monitoramento**
+5. **Definir processo de revisão**
+
+### 2. Monitoramento Contínuo
+
+#### Ferramentas
+- **Prometheus**: Coleta de métricas
+- **Grafana**: Visualização e alertas
+- **PagerDuty**: Gerenciamento de incidentes
+- **Slack**: Notificações em tempo real
+
+#### Automação
+```python
+# Exemplo de verificação automática de SLOs
+def check_slo_compliance():
+    """Verifica conformidade com SLOs"""
+    
+    # Verificar disponibilidade do pipeline
+    pipeline_availability = get_pipeline_success_rate()
+    
+    # Verificar performance de queries
+    query_performance = get_p95_query_time()
+    
+    # Verificar qualidade de dados
+    data_quality = get_data_quality_score()
+    
+    # Calcular conformidade geral
+    overall_compliance = (
+        (pipeline_availability / 99.5) * 0.4 +
+        (100 - (query_performance - 10) / 10 * 100) * 0.3 +
+        data_quality * 0.3
+    )
+    
+    # Gerar alerta se necessário
+    if overall_compliance < 95:
+        send_alert("SLO Compliance Below Threshold", overall_compliance)
+    
+    return {
+        "overall_compliance": overall_compliance,
+        "pipeline_availability": pipeline_availability,
+        "query_performance": query_performance,
+        "data_quality": data_quality
+    }
+```
+
+### 3. Revisão e Ajuste
+
+#### Frequência de Revisão
+- **Semanal**: Revisão de métricas e tendências
+- **Mensal**: Análise de conformidade e incidentes
+- **Trimestral**: Revisão e ajuste dos SLOs
+- **Anual**: Revisão estratégica dos objetivos
+
+#### Processo de Ajuste
+1. **Analisar desempenho atual**
+2. **Identificar gaps e oportunidades**
+3. **Ajustar metas se necessário**
+4. **Comunicar mudanças**
+5. **Atualizar documentação**
+
+---
+
+## 📊 Relatórios
+
+### Relatório Diário
+
+#### Métricas do Dia
+```markdown
+## SLO Report - [Data]
+
+### Overall Health Score: [X]%
+
+#### Pipeline Performance
+- Success Rate: [X]%
+- Average Execution Time: [X] min
+- Failed Executions: [X]
+
+#### Data Quality
+- Completeness: [X]%
+- Accuracy: [X]%
+- Consistency: [X]%
+
+#### Dashboard Performance
+- Average Load Time: [X]s
+- P95 Load Time: [X]s
+- Failed Loads: [X]
+
+### Incidents
+- [ ] Incident 1: [Descrição]
+- [ ] Incident 2: [Descrição]
+
+### Action Items
+- [ ] Action 1: [Descrição]
+- [ ] Action 2: [Descrição]
+```
+
+### Relatório Mensal
+
+#### Análise de Tendências
+- **Evolução dos SLOs**: Gráfico de tendência
+- **Principais Incidentes**: Análise de causas
+- **Melhorias Implementadas**: Detalhes das mudanças
+- **Projeções**: Expectativas para próximo mês
+
+---
+
+## 🎯 Melhoria Contínua
+
+### Identificação de Oportunidades
+
+#### Análise de Gaps
+1. **SLOs não atingidos**: Investigar causas raiz
+2. **Métricas degradantes**: Identificar tendências negativas
+3. **Feedback dos usuários**: Coletar percepções
+4. **Benchmarking**: Comparar com melhores práticas
+
+#### Plano de Ação
+```markdown
+## Plano de Melhoria - [Período]
+
+### Objetivos
+1. [Objetivo 1]
+2. [Objetivo 2]
+3. [Objetivo 3]
+
+### Ações Específicas
+- [ ] **Ação 1**: [Descrição] - [Responsável] - [Prazo]
+- [ ] **Ação 2**: [Descrição] - [Responsável] - [Prazo]
+- [ ] **Ação 3**: [Descrição] - [Responsável] - [Prazo]
+
+### Métricas de Sucesso
+- [Métrica 1]: [Meta]
+- [Métrica 2]: [Meta]
+- [Métrica 3]: [Meta]
+
+### Recursos Necessários
+- [Recurso 1]: [Descrição]
+- [Recurso 2]: [Descrição]
+- [Recurso 3]: [Descrição]
+```
+
+---
+
+## 📝 Histórico de Alterações
+
+| Data | Versão | Alteração | Autor |
+|------|--------|-----------|-------|
+| [DD/MM/YYYY] | 1.0 | Criação inicial | [Nome] |
+| [DD/MM/YYYY] | 1.1 | [Descrição] | [Nome] |
+
+---
+
+## ✅ Checklist de Validação
+
+### Configuração Inicial
+- [ ] **SLOs definidos**: Todos os serviços críticos
+- [ ] **SLIs configurados**: Métricas coletadas
+- [ ] **Alertas ativas**: Notificações configuradas
+- [ ] **Dashboards criados**: Visualizações funcionais
+- [ ] **Documentação completa**: Todos os campos preenchidos
+
+### Operação Contínua
+- [ ] **Monitoramento ativo**: Métricas sendo coletadas
+- [ ] **Alertas funcionando**: Notificações sendo enviadas
+- [ ] **Relatórios gerados**: Entregues no prazo
+- [ ] **Revisões realizadas**: Análises conduzidas
+- [ ] **Ajustes aplicados**: Melhorias implementadas
+
+---
+
+**Status Final:** [ ] ✅ **SLOs ATINGIDOS** | [ ] 🔄 **EM MONITORAMENTO** | [ ] ❌ **NECESSITA AJUSTE**

package/dist/content/skills/specialist-debugging-troubleshooting/MCP_INTEGRATION.md

@@ -0,0 +1,340 @@
+# MCP Integration Guide - Especialista Debugging e Troubleshooting
+
+## 🎯 Visão Geral
+
+Este documento descreve como o MCP deve integrar com a skill de Debugging e Troubleshooting, fornecendo funções descritivas que substituem a execução direta de scripts.
+
+## 🔧 Funções MCP Implementadas
+
+### 1. Função de Inicialização
+
+#### **Nome da Função**
+`initialize_bug_report`
+
+#### **Descrição**
+Cria bug report estruturado com template padrão e placeholders definidos.
+
+#### **Parâmetros**
+```json
+{
+  "bug_id": "string (obrigatório)",
+  "severity": "string (obrigatório: critica|alta|media|baixa)",
+  "description": "string (obrigatório)",
+  "base_dir": "string (opcional)"
+}
+```
+
+#### **Retorno**
+```json
+{
+  "success": boolean,
+  "bug_report_path": "string",
+  "bug_id": "string",
+  "message": "string"
+}
+```
+
+#### **Implementação MCP**
+```python
+async def initialize_bug_report(params):
+    """Inicializa bug report via MCP"""
+    bug_id = params.get("bug_id")
+    severity = params.get("severity")
+    description = params.get("description")
+    base_dir = params.get("base_dir", None)
+    
+    # Executa lógica do init_debugging.py
+    initializer = BugReportInitializer(base_dir)
+    initializer.create_output_directory()
+    
+    report_content = initializer.generate_bug_report(bug_id, severity, description)
+    report_path = initializer.save_bug_report(bug_id, report_content)
+    
+    return {
+        "success": True,
+        "bug_report_path": str(report_path),
+        "bug_id": bug_id,
+        "message": f"Bug report {bug_id} criado"
+    }
+```
+
+---
+
+### 2. Função de Validação
+
+#### **Nome da Função**
+`validate_debugging_quality`
+
+#### **Descrição**
+Aplica validação automática do processo de debugging usando checklist de qualidade (score mínimo 75/100).
+
+#### **Parâmetros**
+```json
+{
+  "bug_report_path": "string (opcional)",
+  "base_dir": "string (opcional)",
+  "min_score": "number (opcional, default: 75)"
+}
+```
+
+#### **Retorno**
+```json
+{
+  "success": boolean,
+  "score": number,
+  "max_score": number,
+  "percentage": number,
+  "status": "string",
+  "feedback": ["string"],
+  "phase_scores": {
+    "reproduce": number,
+    "isolate": number,
+    "understand": number,
+    "fix": number
+  },
+  "report_path": "string"
+}
+```
+
+#### **Implementação MCP**
+```python
+async def validate_debugging_quality(params):
+    """Valida qualidade do debugging via MCP"""
+    bug_report_path = params.get("bug_report_path")
+    base_dir = params.get("base_dir", None)
+    min_score = params.get("min_score", 75)
+    
+    # Executa lógica do validate_fix.py
+    validator = DebuggingValidator(base_dir)
+    
+    if bug_report_path:
+        validator.bug_report_path = Path(bug_report_path)
+    
+    validator.min_score = min_score
+    percentage = validator.run_validation()
+    
+    return {
+        "success": percentage >= min_score,
+        "score": validator.total_score,
+        "max_score": validator.max_score,
+        "percentage": percentage,
+        "status": validator.get_status(percentage),
+        "feedback": validator.feedback,
+        "phase_scores": validator.phase_scores,
+        "report_path": str(validator.report_path)
+    }
+```
+
+---
+
+### 3. Função de Processamento
+
+#### **Nome da Função**
+`process_postmortem`
+
+#### **Descrição**
+Prepara post-mortem estruturado e documentação de lessons learned.
+
+#### **Parâmetros**
+```json
+{
+  "bug_report_path": "string (opcional)",
+  "base_dir": "string (opcional)",
+  "incident_id": "string (obrigatório)"
+}
+```
+
+#### **Retorno**
+```json
+{
+  "success": boolean,
+  "postmortem_created": boolean,
+  "lessons_learned": boolean,
+  "files_created": ["string"],
+  "next_steps": ["string"]
+}
+```
+
+#### **Implementação MCP**
+```python
+async def process_postmortem(params):
+    """Processa post-mortem via MCP"""
+    bug_report_path = params.get("bug_report_path")
+    base_dir = params.get("base_dir", None)
+    incident_id = params.get("incident_id")
+    
+    # Executa lógica do process_postmortem.py
+    processor = PostMortemProcessor(base_dir)
+    
+    if bug_report_path:
+        processor.bug_report_path = Path(bug_report_path)
+    
+    success = processor.run_processing(incident_id)
+    
+    return {
+        "success": success,
+        "postmortem_created": True,
+        "lessons_learned": True,
+        "files_created": [
+            f"docs/bugs/{incident_id}-postmortem.md",
+            f"docs/bugs/{incident_id}-lessons.md"
+        ],
+        "next_steps": [
+            "Review post-mortem com equipe",
+            "Implementar action items",
+            "Atualizar runbooks"
+        ]
+    }
+```
+
+---
+
+## 🔄 Fluxo de Integração
+
+### 1. Detecção de Necessidade
+O especialista detecta quando precisa de automação:
+
+```markdown
+### 1. Inicialização Estruturada
+Use função de inicialização para criar bug report com template padrão.
+```
+
+### 2. Chamada MCP
+O MCP interpreta a necessidade e chama a função apropriada:
+
+```python
+# MCP detecta "inicialização estruturada"
+if "inicialização estruturada" in skill_context:
+    result = await mcp_call("initialize_bug_report", {
+        "bug_id": extracted_bug_id,
+        "severity": extracted_severity,
+        "description": extracted_description
+    })
+```
+
+### 3. Retorno para Skill
+O MCP retorna o resultado para a skill continuar o processo:
+
+```python
+if result["success"]:
+    skill_context["bug_report_path"] = result["bug_report_path"]
+    skill_context["status"] = "initialized"
+    # Continua com próximo passo da skill
+```
+
+---
+
+## 📋 Mapeamento de Comandos
+
+### Comandos da Skill → Funções MCP
+
+| Comando da Skill | Função MCP | Gatilho |
+|------------------|------------|---------|
+| "Use função de inicialização" | `initialize_bug_report` | "inicialização estruturada" |
+| "Aplique validação automática" | `validate_debugging_quality` | "validação automática" |
+| "Use função de processamento" | `process_postmortem` | "processamento de post-mortem" |
+
+---
+
+## 🛡️ Guardrails e Segurança
+
+### 1. Validação de Parâmetros
+```python
+def validate_mcp_params(params, required_fields):
+    """Valida parâmetros obrigatórios"""
+    for field in required_fields:
+        if field not in params:
+            raise ValueError(f"Parâmetro obrigatório: {field}")
+    return True
+```
+
+### 2. Verificação de Permissões
+```python
+def check_mcp_permissions(action, user_context):
+    """Verifica permissões do usuário"""
+    if action == "process_postmortem":
+        # Requer validação prévia
+        if user_context.get("validation_score", 0) < 75:
+            raise PermissionError("Debugging não validado para post-mortem")
+    return True
+```
+
+---
+
+## 📊 Métricas e Monitoramento
+
+### 1. Métricas de Execução
+```python
+mcp_metrics = {
+    "initialize_bug_report": {
+        "calls": 0,
+        "success_rate": 0.0,
+        "avg_duration": 0.0
+    },
+    "validate_debugging_quality": {
+        "calls": 0,
+        "success_rate": 0.0,
+        "avg_score": 0.0
+    },
+    "process_postmortem": {
+        "calls": 0,
+        "success_rate": 0.0,
+        "avg_duration": 0.0
+    }
+}
+```
+
+---
+
+## 🚀 Exemplo de Uso Completo
+
+### Fluxo Real com MCP
+```python
+# 1. Usuário reporta bug
+user_input = "Bug: Login falha com erro 401"
+
+# 2. Skill detecta necessidade
+skill_response = """
+Vou criar um bug report estruturado.
+[Use função de inicialização para criar bug report]
+"""
+
+# 3. MCP executa função
+mcp_result = await mcp_call("initialize_bug_report", {
+    "bug_id": "BUG-001",
+    "severity": "alta",
+    "description": "Login falha com erro 401"
+})
+
+# 4. Skill continua com debugging
+if mcp_result["success"]:
+    skill_response += f"""
+Bug report criado: {mcp_result['bug_report_path']}
+
+Vamos seguir a metodologia de 4 fases:
+1. REPRODUCE: Documentar steps
+2. ISOLATE: Identificar componente
+3. UNDERSTAND: Aplicar 5 Whys
+4. FIX: Corrigir causa raiz
+"""
+
+# 5. Após fix, skill solicita validação
+validation_result = await mcp_call("validate_debugging_quality", {
+    "bug_report_path": mcp_result["bug_report_path"]
+})
+
+# 6. Skill apresenta resultado
+if validation_result["success"]:
+    skill_response += f"""
+✅ Debugging validado com {validation_result['score']}/100 pontos!
+
+[Use função de processamento para criar post-mortem]
+"""
+```
+
+---
+
+**Versão:** 1.0  
+**Framework:** Maestro Skills + MCP Integration  
+**Atualização:** 2026-01-30  
+**Status:** ✅ Ready for MCP Implementation