---
name: prompt-refine
description: Transforma um pedido vago em prompt de excelência — especificação detalhada, inequívoca e estruturada para agentes de IA. Usar quando "refinar prompt", "melhorar prompt", "engenharia de prompts", "prompt para agente", "estruturar instrução IA", "prompt engineering".
allowed-tools: Read, Write, mcp__memory-supabase__search_memories
---

# /prompt-refine — Engenharia de Prompts

Transforma um pedido em linguagem natural num **prompt de excelência** pronto para ser executado por outro agente de IA.

## Quando Usar

- Pedido do utilizador é vago ou incompleto
- Preparar instrução para um agente especializado
- Criar template reutilizável para uma tarefa recorrente
- Garantir qualidade máxima de input antes de executar

## Protocolo

### 1. Pesquisar contexto relevante

```
mcp__memory-supabase__search_memories "<palavras-chave do pedido>"
```

Verificar se há padrões ou decisões anteriores relacionadas.

### 2. Analisar o pedido original

Identificar:
- **O quê** — resultado final esperado
- **Para quê** — objectivo ou problema a resolver
- **Quem** — agente ou utilizador que vai executar
- **Restrições** — limitações técnicas, de formato ou de negócio
- **Lacunas** — o que está implícito mas não dito

Se faltar informação crítica → perguntar antes de estruturar.

### 3. Estruturar o prompt de excelência

Usar este template como base:

```markdown
## Função
[Quem é / que papel assume o agente executante]

## Objectivo
[O que deve ser produzido — resultado concreto e mensurável]

## Contexto
[Informação de fundo necessária para compreender o pedido]

## Requisitos
- [Requisito 1 — obrigatório]
- [Requisito 2 — obrigatório]
- [Restrição ou critério de qualidade]

## Input
[Descrição do que o agente recebe como entrada]

## Output esperado
[Formato, estrutura e conteúdo exacto do resultado]

## Exemplos
### Exemplo positivo (fazer)
[Exemplo concreto do resultado desejado]

### Exemplo negativo (não fazer)
[Exemplo do que deve ser evitado]

## Critérios de sucesso
- [ ] Critério 1
- [ ] Critério 2
```

### 4. Rever antes de entregar

Verificar checklist:
- [ ] Sem ambiguidades — cada instrução tem um único significado possível
- [ ] Completo — nenhuma informação crítica em falta
- [ ] Accionável — o agente pode executar sem fazer suposições
- [ ] Testável — é possível verificar se o output é correcto
- [ ] Conciso — sem redundâncias ou instruções contraditórias

### 5. Entregar com explicação

Apresentar:
1. **Prompt refinado** (em bloco de código copiável)
2. **Decisões tomadas** — o que foi inferido vs. o que estava explícito
3. **Questões em aberto** — se houver ambiguidades que o utilizador deve resolver

## Exemplos de Transformação

### Input vago
> "Cria um agente que analisa clientes"

### Output refinado
```markdown
## Função
Analista de CRM especializado em classificação de clientes

## Objectivo
Gerar um relatório de segmentação de clientes com base em histórico de compras
e interacções, identificando os segmentos de alto, médio e baixo valor.

## Contexto
Base de dados Desk CRM com clientes activos nos últimos 12 meses.
Acesso via mcp__desk-crm-v3__get_customers e mcp__desk-crm-v3__get_payments.

## Requisitos
- Segmentar em 3 níveis: Alto Valor (>5000EUR/ano), Médio (1000-5000EUR), Baixo (<1000EUR)
- Incluir número de projectos activos por cliente
- Formato: tabela Markdown ordenada por valor decrescente

## Input
Lista de IDs de clientes ou "todos" para analisar base completa

## Output esperado
Tabela com: ID, Nome, Segmento, Volume Anual (EUR), Projectos Activos, Última Interacção
```

## Padrões de Qualidade

| Característica | Mau prompt | Bom prompt |
|---|---|---|
| Especificidade | "Analisa dados" | "Calcula receita mensal por cliente em EUR para Q1 2026" |
| Formato output | "Devolve resultados" | "Tabela Markdown com colunas: ID, Nome, Valor, Delta%" |
| Critério sucesso | "Deve ser bom" | "Score de satisfação >85% em teste com 3 utilizadores reais" |
| Contexto | Nenhum | "Sistema usa Desk CRM v3, moeda EUR, fuso Europe/Lisbon" |

---
**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: dev-tools

---

## 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.*