---
name: validate-component
description: Valida skills/agents para alinhamento com procedimentos Hub. Use quando "validar skill", "verificar agent", "audit component", "check procedure compliance", antes de deploy de nova skill/agent. Verifica se componente referencia procedimentos (não duplica), segue padrão de referenciação.
---

# /validate-component - Validador de Componentes

Audita skills e agents para garantir alinhamento com padrão de centralização de procedimentos Hub.

---

## Referências e Documentação

**SEMPRE consultar:**
- **[Hub CLAUDE.md](file:///media/ealmeida/Dados/Hub/CLAUDE.md)** - Secção "Organização de Procedimentos" (padrão referenciação)
- **[/mcp-dev skill](file:///home/ealmeida/.claude/plugins/marketplaces/descomplicar-plugins/infraestrutura/skills/mcp-dev/SKILL.md)** - Exemplo padrão ouro de referenciação

---

## O Que Valida

### 1. Procedimentos Embeddados (RED FLAG)

**Detecta conteúdo que deve estar em PROC-*:**
- ✗ Checklists extensas (>10 itens)
- ✗ Regras de validação detalhadas
- ✗ Troubleshooting guides completos
- ✗ Standards e convenções
- ✗ Best practices longas
- ✗ Workflows complexos passo-a-passo

### 2. Referenciação Correcta (GREEN FLAG)

**Verifica se componente referencia procedimentos:**
- ✓ Secção "Referências e Documentação"
- ✓ Links file:// para PROCs relevantes
- ✓ Descrição breve do que cada PROC cobre
- ✓ Instrução "SEMPRE consultar antes de..."

### 3. Separação Clara

**O que DEVE ficar no componente:**
- ✓ Comandos e templates
- ✓ Instruções operacionais curtas
- ✓ Decisão "quando usar"
- ✓ Exemplos práticos inline

**O que DEVE ir para PROC:**
- ✗ Regras e standards
- ✗ Checklists de validação
- ✗ Troubleshooting detalhado
- ✗ Melhores práticas extensas

---

## Protocolo de Validação

### Para Skills

```
1. LER skill SKILL.md completo

2. VERIFICAR secção "Referências e Documentação":
   - Existe? (GREEN se sim, sugerir criar se não)
   - Tem links file:// para PROCs? (GREEN se sim)
   - Links são relevantes para o domínio da skill?

3. DETECTAR procedimentos embeddados:
   - Procurar padrões: "Checklist", "Steps", "Validação", "Troubleshooting"
   - Se >100 linhas de instruções → SUGERIR extrair para PROC

4. AVALIAR qualidade referenciação:
   - Links funcionam? (teste paths)
   - Descrição do PROC é clara?
   - Indica quando consultar?

5. GERAR relatório (ver formato abaixo)
```

### Para Agents

```
1. LER agent .md completo (frontmatter + system prompt)

2. VERIFICAR system prompt tem secção "Referências":
   - Existe? (GREEN se sim)
   - Tem links file:// para PROCs relevantes?

3. DETECTAR procedimentos embeddados no system prompt:
   - Padrões similares a skills
   - Workflows >50 linhas no prompt

4. AVALIAR se agent conhece procedimentos do seu domínio:
   - wordpress-plugin-developer → deve referenciar PROC-WordPress-*
   - mcp-protocol-developer → deve referenciar PROC-MCP-*

5. GERAR relatório
```

---

## Formato Relatório

```markdown
# Relatório Validação: [nome-componente]

**Tipo:** Skill | Agent
**Path:** [caminho completo]
**Data:** YYYY-MM-DD HH:MM

---

## Status Geral

**Score:** X/10
- ✅ 8-10: Excelente (nada a fazer)
- ⚠️ 5-7: Atenção (melhorias sugeridas)
- ❌ 0-4: Crítico (refactoring necessário)

---

## Checklist Validação

### Referenciação (Peso: 40%)
- [ ] Secção "Referências e Documentação" existe
- [ ] Links file:// para PROCs relevantes
- [ ] Descrição clara do que cada PROC cobre
- [ ] Instrução "SEMPRE consultar antes de..."

### Separação Conteúdo (Peso: 40%)
- [ ] Sem checklists longas (>10 itens) embeddadas
- [ ] Sem troubleshooting extenso embeddado
- [ ] Sem standards/conventions detalhadas embeddadas
- [ ] Sem workflows complexos embeddados

### Qualidade (Peso: 20%)
- [ ] Links file:// funcionam (paths válidos)
- [ ] Referencia PROCs do departamento correcto
- [ ] Instruções operacionais concisas (<50 linhas)

---

## Issues Detectadas

### 🔴 Críticas (Bloqueia Deploy)

1. **[Tipo Issue]**
   - **Localização:** Linha X-Y
   - **Problema:** Descrição
   - **Impacto:** Duplicação procedimento / Info embeddada
   - **Acção:** Extrair para PROC-[Nome].md em [Departamento]/

### ⚠️ Avisos (Recomendado Corrigir)

1. **[Tipo Issue]**
   - **Localização:** Secção X
   - **Problema:** Descrição
   - **Sugestão:** Adicionar referência a PROC-[Nome].md

### ✅ Boas Práticas Observadas

1. Secção "Referências" bem estruturada
2. Links file:// correctos
3. Separação clara comando vs regra

---

## Recomendações

### Imediatas (P1)
1. Extrair checklist linhas X-Y para PROC-[Nome].md
2. Adicionar link file:// para PROC-[Outro].md

### Melhorias (P2)
1. Expandir descrição PROC na referência
2. Adicionar exemplo uso combinado skill + PROC

### Opcional (P3)
1. Considerar criar PROC-[NovoTema].md para conteúdo Y

---

## Procedimentos Relevantes Existentes

| PROC | Departamento | Relevância | Status Link |
|------|--------------|------------|-------------|
| PROC-MCP-Desenvolvimento.md | D7 | Alta | ✅ Referenciado |
| PROC-WordPress-Hardening.md | D7 | Média | ❌ Não referenciado |

---

## Próximos Passos

1. [ ] Corrigir issues críticas (se houver)
2. [ ] Aplicar recomendações P1
3. [ ] Re-validar com /validate-component
4. [ ] Deploy quando score ≥7/10
```

---

## Exemplos de Uso

### Exemplo 1: Skill com Boa Referenciação

```
User: /validate-component /mcp-dev
Assistant:

# Relatório Validação: mcp-dev

**Score:** 9/10 ✅

## Status Geral
Excelente! Padrão ouro de referenciação.

## Issues Detectadas
Nenhuma crítica. Pequena sugestão: expandir descrição PROC-MCP-Session-Recovery.md.

## Boas Práticas
- Secção "Referências e Documentação" completa
- 5 links file:// para PROCs relevantes
- Instruções "SEMPRE consultar antes de..."
- Separação clara: comandos na skill, regras nos PROCs
```

### Exemplo 2: Agent com Procedimentos Embeddados

```
User: /validate-component wordpress-plugin-developer
Assistant:

# Relatório Validação: wordpress-plugin-developer

**Score:** 4/10 ❌

## Issues Críticas

1. **Checklist WordPress Security (60 linhas embeddadas)**
   - Localização: Linhas 234-294
   - Problema: Checklist completa hardening no system prompt
   - Acção: Extrair para PROC-WordPress-Hardening.md (D7-Tecnologia)

2. **Sem Secção Referências**
   - System prompt não referencia nenhum PROC
   - Deve adicionar links para PROC-WordPress-* relevantes

## Recomendações P1

1. Criar PROC-WordPress-Hardening.md com checklist
2. Criar PROC-WordPress-CLI.md com comandos WP-CLI
3. Adicionar secção "Referências" no system prompt
4. Re-validar após refactoring
```

### Exemplo 3: Skill Nova Antes de Deploy

```
User: Criei /easypanel-deploy skill. Validar antes de commit?
Assistant: /validate-component easypanel-deploy

# Relatório Validação: easypanel-deploy

**Score:** 6/10 ⚠️

## Avisos

1. **Workflow Deploy (40 linhas)**
   - Localização: Secção "Deployment Workflow"
   - Problema: Workflow passo-a-passo detalhado
   - Sugestão: Considerar PROC-Deployment-EasyPanel.md (D7/INF)
   - Alternativa: Manter se workflow é core da skill

2. **API Reference Embeddada**
   - 80 linhas de endpoints EasyPanel
   - Sugestão: Mover para references/easypanel-api.md

## Recomendações

Score 6/10 é aceitável para deploy. Opcionalmente:
- Extrair API reference para ficheiro separado (progressive disclosure)
- Se workflow deploy for usado por outros componentes → PROC
```

---

## Integração CI/CD

Para validação automática antes de commit:

```bash
# .git/hooks/pre-commit
if [[ $(git diff --cached --name-only) =~ (skills|agents) ]]; then
  echo "Validating modified components..."
  claude-code /validate-component [path]
fi
```

---

## Critérios de Score

### Score 9-10 (Excelente)
- Secção "Referências" completa e bem estruturada
- Todos os PROCs relevantes referenciados
- Zero procedimentos embeddados
- Separação clara comando vs regra

### Score 7-8 (Bom)
- Secção "Referências" existe
- Maioria dos PROCs referenciados
- Pequenos procedimentos embeddados (<20 linhas)
- Maioria do conteúdo bem separado

### Score 5-6 (Aceitável)
- Algumas referências, mas incompletas
- Procedimentos embeddados médios (20-50 linhas)
- Separação parcial
- Deploy OK mas melhorias recomendadas

### Score 3-4 (Crítico)
- Sem secção "Referências" ou vazia
- Procedimentos longos embeddados (>50 linhas)
- Má separação comando vs regra
- Refactoring necessário antes deploy

### Score 0-2 (Bloqueado)
- Zero referências a PROCs
- Procedimentos extensos embeddados (>100 linhas)
- Duplicação crítica de conteúdo
- Deploy BLOQUEADO até corrigir

---

## Anti-Patterns

**NUNCA:**
- ❌ Aprovar deploy com score <5/10
- ❌ Ignorar issues críticas
- ❌ Validar sem ler componente completo
- ❌ Sugerir extrair conteúdo que é core da skill

**SEMPRE:**
- ✅ Testar links file:// funcionam
- ✅ Verificar departamento correcto dos PROCs
- ✅ Distinguir "core skill" vs "procedimento duplicado"
- ✅ Dar exemplos concretos de refactoring

---

## Referência: /mcp-dev (Padrão Ouro)

Ver secção "Referências e Documentação" em:
`/home/ealmeida/.claude/plugins/.../mcp-dev/SKILL.md`

**O que faz bem:**
- Secção dedicada no topo
- 5 links file:// para PROCs D7-Tecnologia
- Descrição breve de cada PROC
- Instrução clara "SEMPRE consultar antes de criar/modificar MCPs"
- Quick Reference sintética (não duplica PROC)

---

*Skill v1.0.0 | 2026-02-13 | Plugin gestao | Descomplicar®*