claude-plugins/core-tools/skills/metrics/SKILL.md

---
name: metrics
description: Dashboard de metricas de performance de skills e agentes com telemetria quantitativa, trending temporal, alertas de degradacao e calculo de ROI.
---

# SKILL: Performance Metrics Dashboard

## Proposito

Dashboard interactivo de performance de skills e agents com metricas quantitativas automaticas gravadas em Desk DB.

Complementa `/reflect` (qualitativo) com dados quantitativos, `/worklog` com metricas objectivas, e PDCA com decisoes data-driven.

---

## Quando Usar

- Ver performance de skills/agents
- Identificar degradacoes de performance
- Validar melhorias PDCA
- Analise ROI de optimizacoes
- Dashboard executivo de automacao

---

## Comandos

| Comando | Funcao |
|---------|--------|
| `/metrics` | Overview geral (30 dias) |
| `/metrics <skill-name>` | Detalhes de skill especifica |
| `/metrics --project <id>` | Metricas por projecto |
| `/metrics --trend` | Trending temporal |
| `/metrics --compare` | Comparacao vs baseline |
| `/metrics --kb` | Metricas Dify KB |
| `/metrics --roi` | ROI por cliente/projecto |
| `/metrics --export` | Exportar JSON/CSV |
| `/metrics --alerts` | Listar alertas activos |

### Agregacoes Disponiveis

1. **avg** - Medias de performance (padrao)
2. **count** - Contagens por status
3. **trend** - Evolucao temporal (semanal)
4. **compare** - Comparacao com baseline
5. **detailed** - Listagem detalhada

---

## Execucao

### 1. Verificar Tools MCP

```javascript
// Tools necessarios (MCP desk-crm-v3)
const REQUIRED_TOOLS = [
  'mcp__desk-crm-v3__log_skill_metric',
  'mcp__desk-crm-v3__get_skill_metrics'
];
// Se tools nao disponiveis -> query SQL directa como fallback
```

### 2. Query Metricas

**Via MCP (preferencial):**

```javascript
const metrics = await mcp__desk_crm_v3__get_skill_metrics({
  days: 30,
  aggregate: 'avg',
  limit: 10
});
```

**Fallback SQL:** Ver [references/sql-queries.md](references/sql-queries.md)

### 3. Formatar Output

```
Performance Overview (ultimos {days} dias)

Top Skills/Agents:
| Nome           | Usos | Avg Time | Trend | Status |
|----------------|------|----------|-------|--------|
| /orcamento     | 45   | 18min    | -12%  | OK     |
| /lead-approach | 38   | 22min    | +5%   | Alerta |
| wp-plugin-dev  | 32   | 47min    | -8%   | OK     |
```

### 4. Analise Especifica

```javascript
const details = await get_skill_metrics({
  name: skill_name,
  days: 30,
  aggregate: 'detailed'
});

const baseline = await query(
  "SELECT baseline_duration_ms FROM tblskill_agent_baselines WHERE name = ?",
  [skill_name]
);
const improvement = ((baseline - current_avg) / baseline * 100);
```

---

## Alertas Automaticos

```javascript
const degraded = await get_skill_metrics({
  aggregate: 'compare',
  days: 7
});

const alerts = degraded.results.filter(r =>
  r.performance_status === 'DEGRADED'
);

if (alerts.length > 0) {
  // Output alertas e sugerir /reflect para investigar
}
```

### Trigger Reflect se Degradacao

```javascript
if (degradation_pct > 15) {
  // AUTO: Invocar reflect-agent em background
  Task({
    subagent_type: 'reflect-agent',
    background: true,
    model: 'sonnet',
    prompt: `PERFORMANCE DEGRADATION: ${name} +${degradation_pct}%`
  });
}
```

---

## Integracao com Outros Sistemas

| Comando | Foco | Quando Usar |
|---------|------|-------------|
| `/taskforce kb-health` | Saude sistema KB | Visao arquitectural |
| `/metrics --kb` | Performance queries KB | Analise operacional |
| `/metrics --roi` | Valor economico gerado | Justificacao investimento |

**Workflow recomendado:**
1. `/taskforce kb-health` - Verificar gaps e coverage
2. `/metrics --kb` - Analisar performance queries
3. `/metrics --roi` - Calcular ROI para stakeholders

Link Desk CRM: `https://desk.descomplicar.pt/admin/projects/view/65`

---

## Notas Tecnicas

**Tabelas DB:** `tblskill_agent_metrics` (telemetria), `tblskill_agent_baselines` (baselines), `tblskill_agent_pdca_cycles` (PDCA historico)

**Tools:** Implementados em `/opt/desk-crm-v3/src/tools/core/metrics.ts`

**Fallback:** Se tools MCP nao disponiveis, usar queries SQL directas via `sql_direct`.

---

## Conteudo Detalhado

| Referencia | Conteudo |
|------------|----------|
| [references/sql-queries.md](references/sql-queries.md) | Queries SQL completas (top 10, ROI, trending) |
| [references/dashboards-templates.md](references/dashboards-templates.md) | Templates visuais KB, ROI, alertas, export, ASCII charts |

---

**Desk CRM:** Projecto #65, Task #1637