claude-plugins/gestao/skills/knowledge/docs/workflow.md

# Workflow de Pesquisa - /knowledge

Documentação detalhada do processo de pesquisa e routing.

---

## Fluxo Principal

```
┌─────────────┐
│  Pergunta   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Analisar   │ ← Extrair keywords, identificar tema
│   Termo     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Routing   │ ← Consultar config/sources.json
│    Tema     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Pesquisar  │ ← Fonte primária
│  Fonte 1    │
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│ Resultados  │ NO  │  Pesquisar  │
│ Suficientes?├────►│  Fonte 2    │
└──────┬──────┘     └──────┬──────┘
       │ YES               │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│   Agregar   │◄────┤  Fonte 3    │
│  Resultados │     │ (se neces.) │
└──────┬──────┘     └─────────────┘
       │
       ▼
┌─────────────┐
│  Detectar   │ ← Se resultados insuficientes
│   Lacunas   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Resposta   │
│ Estruturada │
└─────────────┘
```

---

## Fase 1: Análise do Termo

### Extracção de Keywords
```
Input: "como configurar crocoblock filters no elementor"
Keywords: [crocoblock, filters, elementor, configurar]
Tema detectado: wordpress
```

### Regras de Detecção
1. Corresponder keywords com `routing[tema].keywords`
2. Se múltiplos temas, usar o mais específico
3. Se nenhum tema, usar pesquisa genérica (todas as fontes)

---

## Fase 2: Routing

### Consulta ao Mapeamento
```javascript
// Pseudocódigo
tema = detectarTema(keywords)
sources = routing[tema].sources

// Ordenar por prioridade
fonte1 = sources[0]  // Primária
fonte2 = sources[1]  // Secundária
fonte3 = sources[2]  // Terciária
```

### Prioridades por Tipo
| Tipo de Pergunta | Fonte Primária | Porque |
|------------------|----------------|--------|
| Técnico/Como fazer | Context7 | Docs actualizados |
| Negócio/Clientes | Supabase | Contexto recente |
| Procedimento | WikiJS | Documentação interna |
| Conhecimento geral | Dify KB | RAG temático |
| Histórico/Decisão | Supabase | Memória longo prazo |

---

## Fase 3: Pesquisa

### Dify KB
```
MCP: mcp__dify-kb__dify_kb_retrieve_segments
Params:
  - dataset_id: [obtido de sources.json]
  - query: [termo original]
  - top_k: 5
```

### WikiJS
```
MCP: mcp__wikijs__search_pages
Params:
  - query: [termo]
Filtrar por paths relevantes do routing
```

### Supabase
```
MCP: mcp__memory-supabase__search_memories
Params:
  - query: [termo]
Filtrar por tags do routing
```

### Context7
```
MCP: mcp__context7__resolve-library-id
MCP: mcp__context7__get-library-docs
Params:
  - libraryName: [biblioteca detectada]
  - topic: [termo específico]
```

### Filesystem
```
Grep em paths do routing:
  - /media/ealmeida/Dados/GDrive/Cloud/EAL/Planeamento/ (Obsidian vault)
  - /media/ealmeida/Dados/GDrive/Projectos/
```

---

## Fase 4: Agregação

### Critérios de Suficiência
- **Suficiente**: ≥1 resultado relevante com conteúdo útil
- **Parcial**: Resultados tangenciais, precisa complemento
- **Insuficiente**: 0 resultados ou irrelevantes

### Formatação de Resposta
```markdown
## Resultado: [termo pesquisado]

### Fonte: [Nome da Fonte]
[Conteúdo encontrado, formatado e resumido]

### Fonte: [Segunda Fonte] (se aplicável)
[Conteúdo complementar]

### Relacionado
- [[Link interno 1]]
- [[Link interno 2]]

### Acções Sugeridas (se aplicável)
- [ ] Criar documentação sobre X
- [ ] Actualizar Y com esta informação
```

---

## Fase 5: Detecção de Lacunas

### Triggers
1. **Zero resultados** em todas as fontes
2. **Tema recorrente** (3+ pesquisas similares sem resultado)
3. **Resultado desactualizado** (>6 meses)
4. **Decisão importante** sem registo

### Acção Automática
```markdown
> [!warning] Lacuna Detectada
> O tema "[X]" não tem documentação adequada.
>
> **Sugestão:**
> - Criar dataset Dify: `[nome-sugerido]`
> - Ou página WikiJS: `[path-sugerido]`
> - Ou guardar em Supabase (se decisão/contexto)
```

### Registo de Lacunas
Adicionar a `config/sources.json` → `gaps`:
```json
{
  "gaps": {
    "dify_missing": ["novo-tema"],
    "wikijs_missing": ["novo-path"],
    "detected_at": "2026-01-25"
  }
}
```

---

## Comandos Especiais

### /kb-save [tema]
```
1. Receber conteúdo a guardar
2. Analisar tipo:
   - Decisão → Supabase (tag: decisao)
   - Procedimento → WikiJS
   - Conhecimento → Dify KB
3. Formatar com metadata
4. Guardar na fonte adequada
5. Confirmar com referência
```

### /kb-gaps
```
1. Ler config/sources.json → gaps
2. Listar lacunas conhecidas
3. Sugerir prioridades baseado em:
   - Frequência de pesquisa
   - Impacto no trabalho
   - Esforço de criação
```

### /kb-new [tema]
```
1. Criar dataset no Dify KB
2. Adicionar estrutura base
3. Actualizar sources.json com novo ID
4. Remover de gaps.dify_missing
```

---

## Métricas de Qualidade

### Pesquisa Bem Sucedida
- [ ] Resultado relevante encontrado
- [ ] Fonte adequada usada
- [ ] Resposta formatada correctamente
- [ ] Links internos incluídos

### Detecção de Lacunas
- [ ] Lacuna identificada quando apropriado
- [ ] Sugestão de acção clara
- [ ] Lacuna registada para futuro

---

## Troubleshooting

| Problema | Causa | Solução |
|----------|-------|---------|
| MCP timeout | Servidor lento | Retry com delay |
| Dataset não encontrado | ID inválido | Actualizar sources.json |
| Resultados irrelevantes | Keywords mal detectadas | Refinar routing |
| Muitas lacunas | Tema novo | Criar conteúdo base |

---

*Workflow v1.0 | 2026-01-25*