# Protocolo de Instrumentação Automática v1.0

**Data:** 2026-02-03
**Propósito:** Auto-registar métricas de execução de skills para análise PDCA

---

## Visão Geral

Toda skill instrumentada deve gravar automaticamente métricas de execução na tabela `tblskill_agent_metrics` do Desk CRM.

## Quando Instrumentar

Skills que:
- Têm baseline definido em `_knowledge-map.json`
- São frequentemente usadas (>5x/semana)
- Estão em processo de optimização

## Estrutura de Instrumentação

### 1. Início de Execução

Ao iniciar a skill, registar:

```javascript
const SKILL_START = Date.now();
const SESSION_ID = crypto.randomUUID(); // ou usar session_id existente
```

### 2. Rastreio de Consultas KB

Se a skill consultar Dify KB:

```javascript
let KB_CONSULTED = false;
let KB_HITS = 0;
let KB_MISS = 0;

// Após cada consulta Dify bem sucedida
KB_CONSULTED = true;
KB_HITS++;

// Se consulta falhou ou sem resultados
KB_MISS++;
```

### 3. Contagem de Tool Calls

```javascript
let TOOL_CALLS = 0;

// Incrementar a cada tool call
TOOL_CALLS++;
```

### 4. Fim de Execução - Gravar Métrica

**Via SQL directo (fallback robusto):**

```sql
INSERT INTO tblskill_agent_metrics (
  type, name, duration_ms, status,
  session_id, task_id, project_id, staff_id,
  kb_consulted, kb_hits, kb_miss, tool_calls,
  error_type, error_message, context_tokens, output_tokens,
  model_used, created_at
) VALUES (
  'skill', '/nome-skill', {DURATION_MS}, '{STATUS}',
  '{SESSION_ID}', {TASK_ID}, {PROJECT_ID}, 25,
  {KB_CONSULTED}, {KB_HITS}, {KB_MISS}, {TOOL_CALLS},
  NULL, NULL, NULL, NULL,
  'opus-4.5', NOW()
);
```

**Via MCP tool (quando disponível):**

```javascript
mcp__desk-crm-v3__log_skill_metric({
  type: 'skill',
  name: '/nome-skill',
  duration_ms: Date.now() - SKILL_START,
  status: 'success', // ou 'error', 'partial'
  session_id: SESSION_ID,
  task_id: CURRENT_TASK_ID,
  project_id: CURRENT_PROJECT_ID,
  staff_id: 25, // AikTop
  kb_consulted: KB_CONSULTED,
  kb_hits: KB_HITS,
  kb_miss: KB_MISS,
  tool_calls: TOOL_CALLS
});
```

## Status Possíveis

| Status | Quando Usar |
|--------|-------------|
| `success` | Skill completou com sucesso |
| `error` | Skill falhou com erro |
| `partial` | Skill completou parcialmente |
| `cancelled` | Utilizador cancelou |

## Campos Opcionais

| Campo | Quando Preencher |
|-------|------------------|
| `task_id` | Se executando dentro de tarefa Desk |
| `project_id` | Se contexto de projecto conhecido |
| `error_type` | Se status = 'error' |
| `error_message` | Se status = 'error' |
| `context_tokens` | Se disponível via API |
| `output_tokens` | Se disponível via API |

## Template para Skills

Adicionar esta secção no final de cada SKILL.md instrumentada:

```markdown
---

## Instrumentação Automática

Esta skill grava métricas automaticamente para análise PDCA.

### Ao Executar Esta Skill

1. **Início:** Registar timestamp inicial
2. **Consultas KB:** Rastrear hits/miss do Dify
3. **Fim:** Gravar métrica via SQL ou MCP

### Query para Gravar (executar no final)

\`\`\`sql
INSERT INTO tblskill_agent_metrics (type, name, duration_ms, status, staff_id, kb_consulted, created_at)
VALUES ('skill', '/nome-skill', {DURACAO_MS}, '{STATUS}', 25, {KB_CONSULTADO}, NOW());
\`\`\`

### Ver Métricas

\`\`\`bash
/metrics /nome-skill
\`\`\`
```

## Integração com /reflect

Se degradação detectada (performance >15% pior que baseline):

1. `/metrics` mostra alerta
2. Sugerir `/reflect` para investigação
3. `/reflect` analisa padrões e propõe melhorias
4. Registar ciclo PDCA em `tblskill_agent_pdca_cycles`

---

**Protocolo v1.0** | 2026-02-03