claude-plugins/gestao/skills/knowledge/SKILL.md

name, description

name	description
knowledge	Router de conhecimento Família A/B. Família A (operacional interna) consultada em paralelo para qualquer pergunta sobre processos, projectos, decisões, histórico. Família B (NotebookLM externa) só para conhecimento conceptual/teórico. v2.1.1

/knowledge — Router Família A/B v2.1.1

Correcção arquitectural 08-04-2026: a v2.0.0 tratava NotebookLM como fonte primária. Isso estava errado — NotebookLM não vê operações, não vê estado real, só tem ebooks e transcripts. Em ~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md está o racional completo.

Princípio de routing

Não é fallback linear. É router por tipo de pergunta:

• Operacional / processual / histórico / decisões / projectos / código interno → Família A em paralelo, consolidar com citação de origem.
• Conceptual / teórico / externo / research / mercado / ebooks → Família B (NotebookLM) com routing por tema (tabela em baixo).
• Ambíguo → perguntar ao utilizador qual o tipo.

Família A — Operacional interna (paralelo, complementares)

Fonte	Tool	Conteúdo
LightRAG	mcp__lightrag__query_document (modo hybrid)	Knowledge graph interno. LightRAG-HKU 1.4.13 completo — REST API + WebUI em rag.descomplicar.pt + PG storage (workspace default) + AGE graph extension. 17 tools MCP disponíveis (ver lista abaixo). 331 docs no Postgres (135 processed + 194 pending + 2 processing + 6 failed).
memory-supabase	mcp__memory-supabase__search_memories(query, threshold=0.7, limit=10)	Memórias persistentes cross-sessão com embeddings. Decisões, contexto, lacunas anteriores.
Memória CC cross-projecto	Grep recursivo em ~/.claude/projects/*/memory/*.md	101 ficheiros em 34 projectos (~261kB). Harness só carrega automaticamente a memória do cwd — este grep é obrigatório para não perder contexto de outros projectos.
Obsidian / Hub	Grep em /media/ealmeida/Dados/Hub/**/*.md	PROCs, QRs, INDEX, frontmatter, procedimentos, histórico.
Desk CRM	mcp__desk-crm-v3__* (tasks, projects, tickets, customers)	Fonte de verdade operacional: tarefas, projectos, clientes, tickets, horas.

Workflow Família A

1. Classificar pergunta como operacional (default para queries internas)
2. Disparar em PARALELO (mesma mensagem, vários tool calls):
   - mcp__lightrag__query_document(query, mode="hybrid")
   - mcp__memory-supabase__search_memories(query, threshold=0.65, limit=8)  [graceful se MCP indisponível]
   - Grep ~/.claude/projects/*/memory/*.md
   - Grep Hub/**/*.md (limitar a pastas relevantes quando possível)
   - Desk CRM search (se query menciona cliente/projecto/tarefa)
3. Consolidar resposta citando origem de cada fragmento
4. Se Família A insuficiente → perguntar ao utilizador ou escalar para Família B

17 tools MCP LightRAG-HKU disponíveis

Consulta / leitura:

• query_document(query, mode) — RAG query. Principal para router. Modos: naive, local, global, hybrid, mix (default: hybrid).
• get_documents() — lista docs com status (processed/pending/processing/failed) e metadata.
• get_pipeline_status() — estado do pipeline de ingestão (busy, job, batchs).
• get_graph_labels() — entity types no knowledge graph.
• check_lightrag_health() — health check do server.

Ingestão:

• insert_document(text) — insere texto único, extrai entidades + relações.
• insert_batch(texts[]) — batch de textos.
• insert_file(path) — insere ficheiro local.
• upload_document(file) — upload binário.
• scan_for_new_documents() — trigger scan do INPUT_DIR (/root/mcp-lightrag/inbox/).

Edição de grafo:

• create_entities, edit_entities, delete_by_entities, merge_entities
• create_relations, edit_relations
• delete_by_doc_ids — remove doc + entidades órfãs.

UI web: https://rag.descomplicar.pt/webui/ com autenticação (AUTH_ACCOUNTS no .env do gateway).

Nota sobre graceful fallback: as tools mcp__* podem estar indisponíveis em sessões específicas por razões de auto-discovery do harness. Se a chamada falhar com "No such tool available", continuar o paralelismo com as outras fontes e reportar a lacuna no output final.

Formato de resposta Família A

## [pergunta]

**LightRAG:** [excerto] _(entidade X, score Y)_
**memory-supabase:** [excerto] _(id N, tags)_
**memory/<projecto>:** [excerto] _(ficheiro)_
**Hub:** [excerto] _(caminho:linha)_
**Desk CRM:** [excerto] _(task #N, projecto #M)_

**Síntese:** [consolidação em 2-3 frases citando as fontes mais fortes]

Regra: nunca responder sem citar fonte. Se 0 fontes, dizer "sem hits em Família A" explicitamente.

---

Família B — Conhecimento externo (NotebookLM)

Quando usar: só para perguntas conceptuais, teóricas, de research externo ou mercado. Nunca para operacional.

Exemplos de queries Família B:

• "Quais são as melhores práticas de Core Web Vitals em 2025?"
• "Como funciona o algoritmo de ranking do YouTube Shorts?"
• "Arquétipos de Jung aplicados a branding"
• "Stoicismo na gestão de equipas"

Workflow Família B:

1. Classificar tema → tabela de routing
2. Consultar max 3 notebooks (performance)
3. mcp__notebooklm-mcp__notebook_query({ notebook_id, query })
4. Se score <70 → fallback a Context7 (docs bibliotecas)

Routing por tema (65 notebooks)

Inventário completo: ~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md

WordPress/Web

Keywords	Notebook	ID
wordpress, wp-cli, config	WordPress Config CLI	fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d
elementor, templates, widgets	WordPress e Elementor	5be0d1a6-00f2-4cd9-b835-978cb7721601
woocommerce, loja, produtos	Documentacao WooCommerce	bd06acff-4b9d-44aa-b3f7-60434bbd6b49
kivicare, ehr, clinica	KiviCare EHR WP	78621405-a5bc-433f-856f-296260a80bd9
seguranca wp, malware, hardening	Ciberseguranca WordPress	5f60adfd-2435-4725-8c12-9c11c5f51d75

Marketing e Conteúdo

Keywords	Notebook	ID
marketing, digital, campanha, funil	Marketing Digital PT	4c595973-ba10-420a-a3bf-e4389e424ad3
marketing avancado, ads, growth	Marketing Digital Avancado	76647e0f-3ae2-4c00-a0a8-f457aebf5655
seo, keywords, ranking, serp	Marketing Digital PT	4c595973-ba10-420a-a3bf-e4389e424ad3
copywriting, persuasao, texto	Copywriting e Persuasao	7b8fec17-d34f-4e3f-a8c6-8231e51f6323
social media, branding, instagram	Social Media e Branding	9053d0e8-dd39-460b-b5ea-e67af3e9a675
video, producao, youtube	Producao de Video e Youtube	058a896e-6c9a-4e51-ae7d-9adb2738bc5f
youtube, monetizacao, compliance	YouTube Monetizacao e Compliance	60a209a7-e205-4d57-a6f3-fef3de61e87a
podcast, audio	Podcast Descomplicar	a5bef96b-a1af-4293-9979-5da46f8d2301
ecommerce, loja online	E-commerce Pratico	226e384e-d4bc-48f4-bb82-7927360436cc
ecommerce portugal, marketplace	E-Commerce Portugal	8a430cf2-ed99-413d-b4bf-a1400deaf49e

Desenvolvimento / Código (externo)

Keywords	Notebook	ID
programacao externa, padroes, api design	Programacao	24947ffa-0019-448a-a340-2f4a275d2eb1
claude code, mcp dev externo	Claude Code	2876d1fe-5cea-4d98-8140-b0e1a81c6bc4
mcp protocolo	Desenvolvimento de MCPs	73102308-70ef-403e-9be9-eae0cfc62d55
ai editor, cursor, copilot	AI Code Editors	57d9c6c9-48ba-4d83-8f71-cc890f348a53
github trends	GitHub Trends	922b7532-ddf3-4dba-9d3c-6d5f83b89378
open source, foss	Open Source Software and Platforms	cabf9821-c1ff-44cb-9bfd-59bda3599792
n8n, workflow automacao	n8n	f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1
perfex dev, hooks externos	Dev PerfexCRM	80606de8-2783-4d36-b08d-5825e6f9a8da
remotion, video code	Remotion	f2b75baa-1ab1-48d3-8f7c-a6a9e516934c

Nota: código do projecto (/Dev/*, plugins locais, MCPs desenvolvidos internamente) é Família A (grep Hub + filesystem), não Família B.

Infraestrutura

Keywords	Notebook	ID
cwp externo	CWP	0ded7bd6-69b3-4c76-b327-452396bf7ea7
cloud, devops patterns	Cloud e Infraestrutura TI	f9a79b5a-649f-4443-afaf-7ff562b6c2e7
proxmox	Proxmox	276ccdde-6b95-42a3-ad96-4e64d64c8d52

Design/UX

Keywords	Notebook	ID
design, branding externo	Design Profissional AItomatizado	b568b13b-0eed-48c9-b513-5c5b7ec0b102
ui, ux, wcag	UI/UX Design	081ca512-8279-4850-b2b9-dff090267482
tipografia, cores	Tipografia e Cor para Web	f97a0d2b-a5b3-4640-b941-3cbb184b1b81

Gestão e Estratégia

Keywords	Notebook	ID
gestao projectos, agile, scrum	Gestao de Projectos e Agile	0c9c079c-a426-486c-99eb-1564d42d37ad
operacoes externas, kpi	Gestao de Operacoes	f9dc59c2-718b-4b12-bd06-095d4bfa3e34
estrategia, empreendedorismo	Estrategia e Empreendedorismo	79d43410-0e29-4be1-881d-84db6bdc239a
transformacao digital, ia negocio	Transformacao Digital e IA	ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8
ai automation stack	AI Automation Stack	929ef67b-c131-4f01-abd0-8b078491a6b7
ai agents curso	AI Agents Intensive Course	f4be0e3f-4d9e-4c5c-a743-9f14427f2e43

Produtos externos / Mercado

Keywords	Notebook	ID
zaia, chatbot	Zaia	087d76f1-e929-49da-9e3c-4edc22b42b3f
zender, whatsapp api	Zender 3	7095e5fa-1465-4496-b1a3-48f2e6e07f79
solar, fotovoltaico	Solar FV Engenharia	03d54e00-aefa-45dc-ba01-f3864a7c3112
opensolar	OpenSolar	0082bcaf-1e17-4b84-87cc-2256b1719b55

Pessoal / SelfRescueProtocol (só se explicitamente pessoal)

Keywords	Notebook	ID
jung, arquetipos	Jung	d5c67d7f-7fe8-4542-9e5c-22403f3193ee
taoismo, wu wei	Taoism	aea85baf-9ddf-4d79-bf07-81391a275b09
adhd, phda	ADHD	a4ff3fd7-fb7c-49a1-94ff-0433193e2338
autismo	Autismo	66eff78e-318f-4a8b-a3c7-039a4124b1ad
heroi, jornada	Essencia de Heroi	6dcd08e8-79d9-4ae0-b6bf-b2ee96717bf2
kintsugi	Auto Kintsugi	82a95c2f-be56-4c4a-a96f-96f6677a6991
somatica, trauma	Psicologia Somatica	3410893b-16a3-4178-9091-42650a41086f
estoicismo	Marcus Aurelius / Stoic	4b986ad4-49da-4604-a423-4fcdf20dd9da

---

Classificador de pergunta (heurística)

Usar estes sinais para decidir Família A vs B:

Sinal na pergunta	Família
Nome de cliente, projecto, tarefa #N, ticket #N	A
"quando", "histórico", "última vez", "decisão", "porque fizemos"	A
Nome de ficheiro, path, skill, plugin, MCP interno	A
"como funciona (abstracto)", "melhores práticas", "teoria de"	B
Nome de biblioteca externa + versão	B (+ Context7)
Pessoal explícito (jung, adhd, estoicismo, …)	B pessoal
Ambíguo	perguntar

---

Comandos

Comando	Uso
/knowledge [pergunta]	Router automático A/B com paralelismo
/kb [pergunta]	Alias curto
/kb-save [conteúdo]	Guardar na fonte adequada (LightRAG se operacional, Supabase se decisão, NotebookLM source_add se externo)
/kb-gaps	Listar lacunas detectadas em memory-supabase

---

Gravar conhecimento (/kb-save)

Router inverso por tipo:

Tipo	Destino	Tool
Decisão / contexto / lacuna	memory-supabase	mcp__memory-supabase__save_memory com tags
Entidade / relação / doc interno	LightRAG	mcp__lightrag__insert_document(text) ou insert_batch(texts)
Procedimento operacional	Hub/06-Operacoes/Procedimentos/	Write PROC-*.md
Conhecimento externo	NotebookLM notebook adequado	mcp__notebooklm-mcp__source_add

---

Detecção e reporte de lacunas

Quando query retorna 0 hits úteis em Família A (o caso relevante) ou <30% score em Família B:

mcp__memory-supabase__save_memory({
  content: `LACUNA: "${query}" — Família A 0 hits, classificada como ${classificacao}.`,
  tags: ["lacuna-kb", classificacao],
  metadata: { query, timestamp, source_families: ["A","B"] }
});

Depois sugerir acção: criar PROC, adicionar ao LightRAG, adicionar fonte ao notebook adequado.

---

Regras operacionais

1. Família A é default. Só escalar para B quando classificador sinalizar externo.
2. Paralelismo obrigatório em Família A. Todas as tools na mesma mensagem (regra global #1: "NEVER run independent tool calls sequentially").
3. Grep cross-projecto obrigatório em ~/.claude/projects/*/memory/*.md — o harness só carrega a memória do cwd, este grep compensa esse gap.
4. Nunca responder sem citar fonte. Se 0 hits, dizer explicitamente.
5. Max 3 notebooks por query Família B.
6. PT-PT sempre na consolidação.
7. Se a pergunta é sobre estado presente (tarefas abertas, tickets, horas, facturas), ir directo ao Desk CRM, não a LightRAG/NotebookLM.

---

Anti-patterns

• ❌ Começar por NotebookLM para perguntas operacionais (era o erro da v2.0.0)
• ❌ Só consultar o cwd e ignorar memory cross-projecto
• ❌ Responder sem citar fonte
• ❌ Chamar Família A em série — tem de ser paralelo
• ❌ Classificar "como funciona o nosso router /knowledge?" como Família B (é Família A — é sobre infra interna)
• ❌ Fallback linear A→B quando a pergunta é claramente externa (vai directo a B)

---

Referências

• references/routing-guide.md — mapeamento detalhado de routing (pendente v2.1 — actualizar)
• ~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md — decisão arquitectural
• ~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md — inventário completo 65 notebooks
• 04-Stack/CHANGELOG.md sessão 3 de 08-04-2026 — recuperação LightRAG e clarificação tools reais

---

Healing log

{"date":"2026-04-08","issue":"v2.0.0 tratava NotebookLM como fonte primaria para tudo","fix":"v2.1.0 router Familia A/B — NotebookLM so para externo","source":"user"}
{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*) apos migracao temporaria da outra sessao","fix":"v2.1.1 restaurado para LightRAG-HKU completo com 17 tools originais (query_document, insert_document, get_pipeline_status, etc), UI em rag.descomplicar.pt, PG storage 331 docs","source":"user"}
{"date":"2026-04-08","issue":"memoria Claude Code fragmentada em ~/.claude/projects/*/memory/ (101 ficheiros, 34 projectos)","fix":"grep cross-projecto obrigatorio no router Familia A","source":"user"}
{"date":"2026-04-08","issue":"mcp__memory-supabase__search_memories pode estar indisponivel no harness","fix":"graceful fallback no router — continuar paralelismo com outras fontes e reportar lacuna","source":"auto"}

---

v2.1.1 | 08-04-2026 | LightRAG-HKU restaurado com 17 tools reais, UI rag.descomplicar.pt, PG storage 331 docs, graceful fallback para MCPs indisponíveis