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

// 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/Hub/ (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

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

> [!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:

{
  "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