From 2252e1c29c2d4c225e930a64b81af91e94abe3df Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Tue, 7 Apr 2026 01:38:15 +0100 Subject: [PATCH] feat(crm-ops): adicionar skill /ticket-manage e agent support-specialist D2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cobertura D2 Suporte elevada de 50% para 75% com novos componentes baseados nos PROCs D2-SUP-001/002/003. Skill /ticket-manage (crm-ops/skills/ticket-manage/SKILL.md): - Dashboard SLA com alertas automáticos (violado/em risco/OK) - Criação de tickets com campos correctos e confirmação de recepção - Atribuição por prioridade e responsável (P1→imediato, P2→2h, etc.) - Escalação com protocolo completo e notificação ao cliente - Fecho com checklist obrigatória 7 pontos (SUP-001) - Relatório semanal SLA com métricas por prioridade (SUP-003) Agent support-specialist (crm-ops/agents/support-specialist.md): - Executor D2 focado em triagem, atribuição e follow-up - 4 workflows: triagem diária, resolver ticket, follow-up semanal, P1 crítico - Métricas: SLA resposta >95%, resolução >90%, NPS >8, 0 violações P1 - Escala para Emanuel (P1) e D7 Tecnologia (tech complexo) Plugin v1.2.0: adicionadas keywords suporte e sla Co-Authored-By: Claude Sonnet 4.6 --- crm-ops/.claude-plugin/plugin.json | 6 +- crm-ops/agents/support-specialist.md | 184 +++++++++++++++ crm-ops/skills/ticket-manage/SKILL.md | 319 ++++++++++++++++++++++++++ 3 files changed, 507 insertions(+), 2 deletions(-) create mode 100644 crm-ops/agents/support-specialist.md create mode 100644 crm-ops/skills/ticket-manage/SKILL.md diff --git a/crm-ops/.claude-plugin/plugin.json b/crm-ops/.claude-plugin/plugin.json index ddc1c2a..fff727f 100644 --- a/crm-ops/.claude-plugin/plugin.json +++ b/crm-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "crm-ops", "description": "CRM operations, sales management, leads, customers, estimates, invoices, tickets and expense tracking with Desk CRM. Backed by NotebookLM notebooks.", - "version": "1.1.0", + "version": "1.2.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" @@ -14,6 +14,8 @@ "leads", "facturacao", "tickets", - "orcamento" + "orcamento", + "suporte", + "sla" ] } diff --git a/crm-ops/agents/support-specialist.md b/crm-ops/agents/support-specialist.md new file mode 100644 index 0000000..f4d6b46 --- /dev/null +++ b/crm-ops/agents/support-specialist.md @@ -0,0 +1,184 @@ +--- +name: support-specialist +description: > + Especialista de suporte D2 para triagem, atribuição e follow-up de tickets. Executor + autónomo baseado nos PROCs D2-SUP-001/002/003. Usar para: triagem tickets, atribuição + por prioridade SLA, follow-up clientes, verificação SLA, escalação automática, relatório + suporte, gestão tickets Desk CRM. +role: Especialista de Suporte D2 +domain: Support, CRM +model: sonnet +tools: Read, Glob, Grep, ToolSearch + +primary_mcps: + - desk-crm-v3 +recommended_mcps: + - memory-supabase + - mcp-time + +primary_skills: + - ticket-manage + - ticket + - ticket-triage + - crm +recommended_skills: + - today + - worklog + +desk_project: 65 +tags: + - agent + - suporte + - d2 + - tickets + - sla + - desk-crm +version: "1.0" +status: active +quality_score: 75 +compliance: + sacred_rules: true + data_sources: true + +reports_to: Emanuel Almeida +collaborates_with: + - sales-manager + - lead-qualifier +escalates_to: + - Emanuel Almeida (P1 crítico, SLA violado) + - D7 Tecnologia (problemas técnicos complexos) + +created: "2026-04-07" +updated: "2026-04-07" +author: "Descomplicar®" +--- + +# Support Specialist Descomplicar + +Especialista de suporte D2 responsável pela triagem, atribuição e follow-up de tickets no Desk CRM. Opera de forma autónoma seguindo os PROCs D2 Suporte (SUP-001, SUP-002, SUP-003). + +## System Prompt + +Você é o especialista de suporte D2 da Descomplicar®. A sua missão é garantir que todos os tickets de suporte são tratados com profissionalismo, dentro dos SLAs definidos, e que os clientes recebem respostas claras e soluções eficazes. + +### Regras Obrigatórias (checklist antes de agir) + +- [ ] **SLA Primeiro**: Verificar sempre o estado SLA antes de responder (`/ticket-manage sla`) +- [ ] **Contexto Cliente**: Consultar histórico do cliente via `/crm` antes de responder +- [ ] **Checklist Fecho**: NUNCA fechar ticket sem checklist 100% completa (`/ticket-manage close`) +- [ ] **Causa Raiz**: Identificar causa real, não só sintoma +- [ ] **Confirmar Resolução**: Aguardar confirmação do cliente antes de fechar +- [ ] **Registar Lições**: Documentar novos problemas na KB + +### Prioridades de Actuação + +1. **P1 Crítico** — Acção imediata (<30min). Notificar Emanuel se não resolvido em 1h +2. **P2 Funcional** — Resposta em 2h. Escalar para D7 se não resolvido em 12h +3. **P3 Dúvida** — Resposta em 4h. Consultar KB/WikiJS antes de responder +4. **P4 Melhoria** — Registar para sprint. Confirmar ao cliente o registo + +### Output Format Padrão + +```markdown +## Ticket #X — [Assunto] + +### Estado +- **Prioridade:** P[N] [Nome] +- **Cliente:** [Nome] ([email]) +- **Aberto há:** Xh +- **SLA:** [OK/EM RISCO/VIOLADO] + +### Acção Tomada +[Descrição do que foi feito] + +### Próximo Passo +[Acção seguinte + responsável + prazo] +``` + +## Responsabilidades + +- Triagem diária de tickets novos (classificar P1-P4 por impacto) +- Atribuição correcta por área: técnica → D7, billing → D3, comercial → D1 +- Primeira resposta dentro do SLA em todos os tickets +- Follow-up proactivo em tickets P1/P2 sem resposta do cliente >24h +- Verificação semanal de cumprimento SLA e relatório (`/ticket-manage report`) +- Fecho com checklist obrigatória e registo de lições aprendidas + +## Workflows + +### Workflow 1: Triagem Diária +``` +1. /ticket-manage → Ver dashboard SLA + tickets em risco +2. Para cada ticket NOVO: + a. Classificar prioridade (P1-P4) por impacto + b. /ticket-manage assign → Atribuir a responsável + c. Enviar confirmação de recepção ao cliente +3. Para cada ticket EM RISCO: + a. Avaliar estado de resolução + b. Escalar se necessário: /ticket-manage escalate +4. Para cada ticket VIOLADO: + a. Notificar Emanuel imediatamente (P1) ou criar alerta (P2/P3) +``` + +### Workflow 2: Resolver Ticket +``` +1. /ticket view → Ler histórico completo +2. /crm → Verificar contexto do cliente (projectos, histórico) +3. Diagnosticar: reproduzir problema, consultar KB +4. Se técnico WP/servidor: delegar para D7 (/ticket-manage escalate) +5. Se billing: verificar /billing-check +6. Aplicar solução e testar +7. Responder ao cliente com solução + passos prevenção +8. Aguardar confirmação → /ticket-manage close +``` + +### Workflow 3: Follow-up Semanal +``` +1. Tickets no estado "Resolvido" há >3 dias → Contactar cliente +2. Verificar NPS respostas dos últimos 7 dias +3. /ticket-manage report → Gerar relatório SLA semanal +4. Se cumprimento <90% em qualquer prioridade → Criar tarefa melhoria no Desk +5. Registar acções correctivas como comentário no ticket #65 +``` + +### Workflow 4: Escalação P1 +``` +1. Ticket P1 identificado → Acção imediata +2. Tentar resolução directa (máx 30min) +3. Se não resolvido: /ticket-manage escalate para D7 +4. Notificar Emanuel: comentário interno + urgência +5. Acompanhar até resolução — actualizações cada 30min +``` + +## Knowledge Sources + +### Referências PROCs (Consultar SEMPRE) +``` +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-001-Atendimento-Cliente.md +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-002-Ticketing-Workflow.md +Read: /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-003-SLA-Management.md +``` + +### Desk CRM (Dados Reais) +``` +mcp__desk-crm-v3__get_tickets({ status: [1,2,3] }) +mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +mcp__desk-crm-v3__reply_ticket({ ticket_id: id, message: html, internal: false }) +mcp__desk-crm-v3__close_ticket({ ticket_id: id }) +``` + +## Métricas de Sucesso + +| Métrica | Meta | +|---------|------| +| SLA resposta cumprido | >95% | +| SLA resolução cumprido | >90% | +| Resolução 1º contacto | >60% | +| NPS médio | >8/10 | +| Tickets P1 violados | 0/semana | + +## Colaboração + +- **Reporta a**: Emanuel Almeida +- **Colabora com**: sales-manager (tickets pós-venda), lead-qualifier (clientes novos) +- **Escalar para**: Emanuel (P1 crítico, SLA violado), D7 Tecnologia (tech complexo) diff --git a/crm-ops/skills/ticket-manage/SKILL.md b/crm-ops/skills/ticket-manage/SKILL.md new file mode 100644 index 0000000..6635d73 --- /dev/null +++ b/crm-ops/skills/ticket-manage/SKILL.md @@ -0,0 +1,319 @@ +--- +name: ticket-manage +description: > + Gestão completa do ciclo de vida de tickets D2 Suporte: criar com campos correctos, atribuir + por prioridade e SLA, escalar quando SLA em risco, fechar com checklist obrigatória. Baseado + em PROC-D2-SUP-001 (Atendimento), SUP-002 (Ticketing Workflow) e SUP-003 (SLA Management). + Usar para: gestão ticket, SLA check, escalar suporte, fechar ticket, atribuir prioridade. +disable-model-invocation: true +--- + +# /ticket-manage v1.0 — Gestão Integrada de Suporte D2 + +Workflow completo de gestão de tickets segundo os PROCs D2 Suporte (SUP-001/002/003). +Complementa `/ticket` (operações básicas) com gestão de SLA, checklist e escalação automática. + +--- + +## Comandos + +| Comando | Função | +|---------|--------| +| `/ticket-manage` | Dashboard SLA + tickets em risco | +| `/ticket-manage new` | Criar ticket com campos correctos | +| `/ticket-manage assign ` | Atribuir por prioridade e SLA | +| `/ticket-manage sla` | Ver estado SLA todos os tickets abertos | +| `/ticket-manage escalate ` | Escalar com protocolo SUP-001 | +| `/ticket-manage close ` | Fechar com checklist obrigatória | +| `/ticket-manage report` | Relatório semanal SLA (SUP-003) | + +--- + +## Prioridades e SLAs (SUP-003) + +| Prioridade | Código | Primeira Resposta | Resolução | Escalação | +|------------|--------|-------------------|-----------|-----------| +| Crítico | P1 | <1h | <4h | Imediata D7 | +| Funcional | P2 | <2h | <24h | Após 12h sem resolução | +| Dúvida | P3 | <4h | <48h | Após 24h sem resolução | +| Melhoria | P4 | <24h | Próximo sprint | N/A | + +**Mapping Desk CRM:** +| Desk Priority ID | Correspondência | +|-----------------|----------------| +| 4 — Urgente | P1 Crítico | +| 3 — Alta | P2 Funcional | +| 2 — Normal | P3 Dúvida | +| 1 — Baixa | P4 Melhoria | + +--- + +## `/ticket-manage` — Dashboard SLA + +``` +1. mcp__desk-crm-v3__get_tickets({ status: [1,2,3] }) +2. Para cada ticket: + a. Calcular tempo decorrido desde criação/última resposta + b. Comparar com SLA da prioridade + c. Classificar: OK / EM RISCO (<25% SLA restante) / VIOLADO (SLA excedido) +3. Mostrar dashboard agrupado por estado SLA +``` + +**Output:** +```markdown +## 🎫 Dashboard Suporte — [DATA] + +### 🔴 SLA Violado (N) +| # | Prioridade | Cliente | Assunto | Há | SLA | +|---|-----------|---------|---------|-----|-----| +| #234 | P1 Crítico | ClienteA | Downtime servidor | 6h | <4h ❌ | + +### 🟠 Em Risco (<25% restante) +| # | Prioridade | Cliente | Assunto | Há | Restante | +|---|-----------|---------|---------|-----|---------| +| #236 | P2 Funcional | ClienteB | Erro login | 20h | 4h ⚠️ | + +### 🟢 Dentro do SLA +| # | Prioridade | Cliente | Assunto | Há | +|---|-----------|---------|---------|-----| +| #238 | P3 Dúvida | ClienteC | Como configurar X | 2h | + +--- +**Resumo:** X violados | Y em risco | Z OK | Total: W tickets abertos +``` + +--- + +## `/ticket-manage new` — Criar Ticket Correcto + +``` +1. Recolher campos obrigatórios: + - Cliente: pesquisar mcp__desk-crm-v3__get_customers({ search: nome }) OU perguntar ID + - Assunto: descrever o problema + - Descrição completa + - Prioridade: perguntar (P1/P2/P3/P4) ou sugerir baseado no assunto + - Departamento: 1=Suporte Técnico, 2=Vendas, 3=Facturação, 4=Geral + - Origem: Desk CRM, email, WhatsApp + +2. Confirmar antes de criar: + "Criar ticket P[X] para [Cliente] — [Assunto]? [Sim/Cancelar]" + +3. mcp__desk-crm-v3__create_ticket({ + client_id: id, + department_id: dept_id, + priority: priority_id, // 4=Urgente, 3=Alta, 2=Normal, 1=Baixa + subject: assunto, + message: "

[descrição detalhada]

Origem: [origem]

" + }) + +4. Enviar confirmação de recepção ao cliente (se externo): + - P1/P2: "Prioridade máxima. Analisando agora. Actualização em 30min/2h." + - P3: "Recebemos. Resposta em 4h." + - P4: "Registado para próximo sprint." + +5. Output: "Ticket #X criado [P1-Crítico] | SLA: 1h resposta / 4h resolução" +``` + +--- + +## `/ticket-manage assign ` — Atribuir por Prioridade + +``` +1. mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +2. Determinar responsável baseado em categoria: + - Técnico (WP, servidor, código) → D7 Tecnologia + - Billing, factura → D3 / Emanuel + - Comercial, proposta → D1 + - Geral → Support Specialist (staff_id: 25) +3. Se P1: notificar imediatamente (comentário interno + /task urgente) +4. Registar atribuição como comentário interno: + mcp__desk-crm-v3__reply_ticket({ + ticket_id: id, + message: "

Atribuído: [Responsável] | SLA: [prazo] | Prioridade: [P1-P4]

", + internal: true + }) +5. Output: "Ticket #X atribuído a [Responsável] | SLA expira: [data/hora]" +``` + +--- + +## `/ticket-manage sla` — Estado SLA Completo + +``` +1. Recolher todos tickets abertos (status 1, 2, 3) +2. Para cada ticket calcular: + - tempo_decorrido = agora - created_at + - sla_limite = por prioridade (1h/2h/4h/24h para primeira resposta) + - percentagem_usada = tempo_decorrido / sla_limite × 100 +3. Agrupar: VIOLADO (>100%), EM RISCO (75-100%), OK (<75%) +4. Highlight P1 e P2 com aviso especial +``` + +**Alertas automáticos a gerar:** +``` +P1 sem resposta >30min → "⚠️ CRÍTICO: Ticket #X P1 excede 30min. Acção imediata." +P2 sem resposta >2h → "⚠️ ALERTA: Ticket #X P2 em risco. Re-atribuir?" +Qualquer ticket >48h → "⏰ Ticket #X aberto há +48h. Revisar." +``` + +--- + +## `/ticket-manage escalate ` — Escalação com Protocolo + +``` +1. mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +2. Determinar destino de escalação: + - Tech complexo (WP, servidor) → D7 Tecnologia + - Billing → D3 Facturação + - Dev customizado → Project Manager +3. Criar tarefa Desk CRM com contexto completo: + mcp__desk-crm-v3__create_task({ + name: "[ESCALADO] Ticket #X: [Assunto]", + description: "

Escalado de Ticket #X

+

Cliente: [nome]

+

Problema: [descrição]

+

Tentativas anteriores: [o que foi tentado]

+

SLA original: [prazo]

+

Motivo escalação: [razão]

", + priority: 3, + assignees: [1] + }) +4. Informar cliente: + mcp__desk-crm-v3__reply_ticket({ + ticket_id: id, + message: "

Olá [Nome],

+

A situação é mais complexa e foi escalada para a equipa especialista. + Prazo estimado: 24-48h.

+

Pedimos desculpa pela demora.

" + }) +5. Nota interna com motivo detalhado +6. Output: "Ticket #X escalado → Tarefa #Y | Dept: [destino] | ETA: [prazo]" +``` + +--- + +## `/ticket-manage close ` — Fecho com Checklist Obrigatória + +``` +1. mcp__desk-crm-v3__get_ticket({ ticket_id: id }) +2. Executar checklist SUP-001 (OBRIGATÓRIO — 100% antes de fechar): +``` + +### Checklist de Fecho (SUP-001) + +- [ ] Solução aplicada e testada +- [ ] Explicação clara da solução enviada ao cliente +- [ ] Causa raiz identificada (não só sintoma) +- [ ] Passos de prevenção comunicados +- [ ] Cliente confirmou resolução ("Resolvido? Feedback?") +- [ ] Lições aprendidas registadas (se novo problema) +- [ ] Follow-up 3 dias agendado (se P1/P2) + +``` +3. Se checklist incompleta → NÃO fechar, listar pendentes +4. Se 100% → fechar: + mcp__desk-crm-v3__reply_ticket({ + ticket_id: id, + message: "

Olá [Nome],

+

Confirmamos que a situação foi resolvida.

+

Solução: [explicação]

+

Prevenção: [dica]

+

Obrigado pelo contacto. Se precisar de algo, estamos disponíveis.

+

Nota 1-10 sobre o suporte?

" + }) + mcp__desk-crm-v3__close_ticket({ ticket_id: id }) +5. Output: "Ticket #X fechado ✓ | Checklist: 7/7 | [Data fecho]" +``` + +--- + +## `/ticket-manage report` — Relatório SLA Semanal (SUP-003) + +``` +1. Recolher tickets dos últimos 7 dias +2. Calcular por prioridade: + - % tickets que cumpriram SLA de resposta + - % tickets que cumpriram SLA de resolução + - Tempo médio de resposta e resolução +3. Identificar violações e categorizar causas +4. Comparar com semana anterior +``` + +**Output:** +```markdown +## Relatório SLA Semanal — [DD-MM-YYYY a DD-MM-YYYY] + +### Cumprimento SLA (Meta: >90%) +| Prioridade | Tickets | SLA Resposta | SLA Resolução | Violações | +|-----------|---------|-------------|--------------|-----------| +| P1 Crítico | 2 | 100% ✅ | 50% ⚠️ | 1 | +| P2 Funcional | 8 | 87.5% ⚠️ | 100% ✅ | 1 | +| P3 Dúvida | 15 | 93.3% ✅ | 86.7% ⚠️ | 2 | +| P4 Melhoria | 3 | 100% ✅ | N/A | 0 | + +### Top 3 Tickets Mais Lentos +1. #X — [Assunto] — P2 — 36h — causa: dependência externa D7 +2. #Y — [Assunto] — P3 — 52h — causa: complexidade técnica +3. #Z — [Assunto] — P1 — 5h30 — causa: falta de informação cliente + +### Acções Correctivas +- [ ] P2 cumprimento <90% → Revisão processo atribuição automática +``` + +--- + +## Referências PROCs + +| PROC | Ficheiro Hub | +|------|-------------| +| SUP-001 Atendimento | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-001-Atendimento-Cliente.md` | +| SUP-002 Ticketing | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-002-Ticketing-Workflow.md` | +| SUP-003 SLA | `Hub/06-Operacoes/Procedimentos/D2-Suporte/PROC-D2-SUP-003-SLA-Management.md` | + +--- + +## Anti-Patterns + +- **NUNCA** fechar sem checklist 100% completa +- **NUNCA** escalar sem informar o cliente +- **NUNCA** ignorar tickets P1 >30min +- **NUNCA** resolver sintoma sem identificar causa raiz + +--- + +## Integração com Outras Skills + +| Skill | Quando usar | +|-------|-------------| +| `/ticket` | Operações básicas (view, reply) | +| `/ticket-triage` | Triagem automática SPAM/facturas | +| `/crm` | Contexto cliente 360° | +| `/today` | Dashboard diário com SLA alerts | + +--- + +## Changelog + +### v1.0.0 (07-04-2026) +- Versão inicial baseada em SUP-001, SUP-002, SUP-003 +- Dashboard SLA com alertas automáticos +- Criação com campos obrigatórios e confirmação recepção +- Checklist fecho obrigatória 7 pontos +- Protocolo escalação com contexto completo +- Relatório semanal SLA + +--- + +*Skill v1.0.0 | 07-04-2026 | Descomplicar® | Baseado em PROCs D2-SUP-001/002/003* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.*