wiki-query

name	wiki-query
description	Responde pergunta ancorada no wiki do pj_* (docs/ + references/) usando qmd + leitura de páginas, sempre com citações ([[wikilinks]] e [@citekeys]). Oferece arquivar a resposta como finding em docs/wiki/findings/ (ou docs/findings/ em projetos sem docs/wiki/) quando útil. NÃO é para perguntas de código.
when_to_use	Quando o usuário perguntar "o que a literatura diz sobre X", "compare Y e Z", "gere tabela comparativa", "resuma os achados sobre W", "quais decisões tomamos sobre Z", ou qualquer pergunta aberta cujo contexto esteja no wiki.
argument-hint	<pergunta>
allowed-tools	Read Glob Grep Bash(qmd *) Bash(prumo *) Bash(cat *) mcp__qmd__query mcp__qmd__search
prumo	{"version":"1.0.0","schema":"WikiQueryResponse/v1","determinism":"agentic","agent_compat":["claude-code"],"cost_estimate":"~5-15k tokens (depende da cobertura)","inputs":{"question":"required"},"requires":["qmd"]}

Wiki Query — responder com citações e arquivar

Preflight (contrato ADR-0019) — execute ANTES de qualquer operação desta skill:

1. Busca semântica (qmd): se as tools MCP do qmd não estiverem no seu inventário NESTA sessão, diga isso explicitamente ("busca semântica indisponível — resultados via leitura direta, mais lentos/parciais") e prossiga só no fallback documentado por esta skill; sem fallback, recuse a operação com o hint do prumo doctor. Se precisar do stack completo, roteie para /prumo-assist:start.

Recusar-se a operar sem dependência NÃO é falha — é o contrato fail-closed (D1): operação exata nunca é simulada.

Opera sobre o wiki estruturado em /docs/wiki-schema.md (monorepo). Usa qmd (via MCP mcp__qmd__* se disponível; senão via Bash("qmd …")) para busca híbrida.

Pressupostos

• cwd é um pj_* com docs/_index.md, docs/_log.md e subdirs.
• qmd está instalado (ver docs/operations.md do monorepo) e o wiki foi indexado ao menos uma vez (qmd collection add . --name <pj> + qmd embed).
• Se não indexado, fluxo ainda funciona usando só _index.md + Grep + Read, mas resposta perde cobertura semântica.
• O CLI prumo precisa estar no PATH (rode prumo doctor; se ausente: uv tool install git+https://github.com/raphaelfh/prumo-assist).

Fluxo

1. Entender a pergunta

Se a pergunta for ambígua ou genérica ("tudo sobre X"), pedir refinamento em uma rodada — nunca mais de uma. Se o usuário insistir, prosseguir com a interpretação mais provável e deixar claro na resposta.

2. Localizar candidatas

1. Read docs/_index.md → identificar seções/entidades/conceitos relacionados.
2. Busca qmd (se MCP disponível):
   • mcp__qmd__query "<pergunta>" (hybrid com rerank) → top 10.
   • Fallback BM25: mcp__qmd__search.
3. Fallback sem qmd: Grep com termos-chave em docs/ references/notes/.
4. Se o tópico é bibliográfico puro, considerar também references/_references.bib e /prumo-assist:paper-manager list.

3. Ler as páginas mais relevantes

Ler ≤ 5–8 páginas selecionadas na íntegra (não só trechos). Extrair:

• Claim (o que cada página afirma sobre a pergunta).
• Evidência (fonte citada pela página — paper, source, notebook, decision).
• Ressalva (limitações, coorte específica, dataset).

4. Sintetizar resposta

Formato padrão (adaptar quando a pergunta pedir tabela/diagrama explícito):

**Resposta curta:** <2–3 linhas direto ao ponto>

**Detalhes:**
- <bullet 1> — ver [[página-a]], [@citekey]
- <bullet 2> — ver [[página-b]]
- <bullet 3> — ver [[finding-anterior]]

**Ressalvas:**
- <limitação 1>
- <limitação 2>

**Gaps identificados** _(opcional)_:
- <nenhuma página cobre X — candidato a /prumo-assist:wiki-ingest ou pergunta a ir buscar na literatura>

Regras:

• Toda afirmação tem citação (wikilink [[…]] ou citação [@citekey]). Sem afirmações sem fonte.
• Nunca inventar citekey — se uma claim não tem fonte no wiki, marcar explicitamente como gap.
• Preferir tabelas quando a pergunta for comparativa (| modelo | AUROC | coorte | ... |).

5. Oferecer arquivamento

Depois da resposta, perguntar exatamente uma vez:

Quer arquivar essa resposta como finding? (docs/wiki/findings/<slug>.md) — útil se a síntese for reutilizada.

Se sim, executar via Bash:

cat <<'BODY' | prumo wiki finding \
    --slug "<slug>" \
    --title "<pergunta ou síntese>" \
    --date "<hoje ISO>" \
    --tags '[<tags JSON>]' \
    --sources '[<wikilinks JSON>]' \
    --generator wiki-query --json
## Pergunta

<pergunta>

## Resposta consolidada

<resposta>

## Evidências

<lista de wikilinks>

## Limitações

<ressalvas>
BODY

prumo wiki finding cria o arquivo e atualiza _index.md e _log.md em uma operação.

Se não: registrar no log via:

cat <<'LOG' >> docs/_log.md

## [<data>] wiki-query | <pergunta curta>

- Respondida sem arquivar.
LOG

6. Visualizações inline

Quando a resposta pedir gráfico (comparação numérica, distribuição, timeline):

• Gerar bloco Python com seaborn + matplotlib (ver rule .claude/rules/coding_style.md), renderizado em notebook ou salvo em docs/wiki/findings/_assets/<slug>.png referenciado no markdown do finding.
• Plotly só se o usuário pedir explicitamente um dashboard interativo.

Boundaries

• Não executa notebooks nem roda código de modelagem — isso é escopo das skills clinical-metrics, data-cleaning, etc.
• Não cria páginas concept/entity — isso é /prumo-assist:wiki-ingest.
• Limite de leitura: até 8 páginas por query para manter contexto enxuto. Se a pergunta for enorme, quebrar em sub-perguntas e rodar em sequência.

Erros comuns

• qmd retorna 0 resultados → rodar qmd embed antes; ou recair em Grep + Read docs/_index.md.
• Usuário pergunta algo que não está no wiki → responder "Não há páginas sobre isso no wiki" + sugerir /prumo-assist:wiki-ingest com fontes candidatas + registrar no log como query | <pergunta> — gap.
• Resposta exige mais de 8 páginas → pedir ao usuário para refinar OU responder em partes e arquivar como 2 findings ligados por related:.