wiki-query

Query — Ask about the wiki

Follow wiki/CONVENTIONS.md for format conventions, links, and language.

Language

Write the artifact in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.

Project root

This skill writes artifacts at paths relative to the project root (the repo where the work happens), not the agent's current working directory.

• If invoked from inside the project, use the relative paths shown in this skill.
• If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend <project-root>/ to every artifact path.
• When the project root is ambiguous, confirm with the user via the harness question tool before writing.

Prompting

Follow the project-wide convention in CLAUDE.md / AGENTS.md ("Skill Prompting Conventions"). Use the harness's structured-question tool — AskUserQuestion (Claude Code), ask_user_question (Codex), or question (OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.

Decision point	Why structured	Suggested options
Search strategy	Affects recall vs precision	QMD MCP · QMD CLI · grep/glob fallback
Answer language	Locale alignment	Wiki language · User language · Bilingual

Free-form prompts (no structured tool):

• The actual query text

No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under Open questions (or equivalent) and proceed without blocking.

Query language alignment

When the user's language differs from the wiki language, translate the retrieval query into the wiki language before searching. Determine the wiki language from .wiki-guardrails.yml (query_language or language), then from wiki frontmatter/index if guardrails are absent. Keep exact product names and code identifiers unchanged.

• Write intent:, vec:, and hyde: in the wiki language.
• Use lex: for exact terms from both languages when useful.
• Answer the user in the user's language unless they ask otherwise.
• If translation is uncertain, say which terms were translated and keep the original terms in lex:.

Retrieval — prefer QMD when available

The recommended retrieval engine is QMD (local hybrid search: BM25 + vector + LLM reranking). Setup is one-time per repo — see docs/wiki/qmd-setup.md in this skills repo.

Detect availability before each query:

• MCP available (mcp__qmd__status and mcp__qmd__query tools registered) → use the MCP tools.
• CLI available (which qmd succeeds) → use qmd query --json --files --min-score 0.4.
• Neither available → fall back to the grep/index path described below. Tell the user once that QMD is not configured and point them to docs/wiki/qmd-setup.md.

Never run qmd embed, qmd update, or qmd collection add automatically — those are owner-run setup commands. The skill only queries an already-built index.

Steps

1. Plan the search — turn the user's question into a structured query document. Always provide an intent: line so reranking and snippet extraction stay anchored to the actual goal:

   intent: <one-sentence framing of what the user actually wants>
   lex: <exact terms / phrases / -negations>
   vec: <natural-language paraphrase of the question>
   hyde: <one short paragraph that looks like the ideal answer>
   

   Drop a sub-query if it does not add signal (a glossary lookup needs only lex; a "how does X work" is mostly vec/hyde).

2. Retrieve via QMD

   • MCP: call mcp__qmd__query with the structured searches array (or the multi-line q string) and the intent field. Restrict by collections when the question is scoped to a single collection vs cross-repo.
   • CLI: qmd query "$(cat <<EOF intent: ... lex: ... vec: ... hyde: ... EOF )" --json --files -n 8 --min-score 0.3
   • Read the top 3-5 hits with mcp__qmd__get / mcp__qmd__multi_get (or qmd get / qmd multi-get on the CLI). Fetch the full body when the snippet is borderline; honor the context field returned by QMD — it carries collection-level guidance the owner curated.

3. Fallback path (no QMD)

   • Read wiki/index.md and use the "By topic" table to locate likely pages.
   • Use grep/Glob with the keywords distilled in step 1.
   • Read the identified pages in full.

4. Synthesize the answer:

   • Direct answer to the question.
   • Cite the wiki pages used with links: [page](wiki/path.md) (use the path returned by QMD, not the docid).
   • If sources contradict each other, present the different viewpoints and flag the conflict.
   • If the information does not exist in the wiki, say so explicitly and suggest sources that could be ingested.

5. Assess whether the answer has lasting value

   • If the answer synthesizes multiple pages in a new and useful way → offer to save it as a page in wiki/sources/ (cross-cutting summary) or as a new section in an existing page.
   • If it is a simple one-off answer → no need to save.

6. Log (only if the query resulted in a wiki update):

   ## [YYYY-MM-DD] query | <question summary>
   - Retrieval: qmd | grep-fallback
   - Pages consulted: ...
   - Result saved: yes/no (which page, if yes)
   

Rules

• Answer first based on the wiki — do not re-synthesize from scratch using code or external sources when the answer already exists.
• Always supply an intent: line to QMD — it is the strongest single lever for relevance.
• Trust QMD's context field — it reflects curated metadata (e.g. raw/ is not the source of truth). Do not "correct" it from training intuition.
• If you cannot find the information, suggest which sources could be ingested to cover the gap.
• Always cite the wiki pages used.
• If the question reveals a gap, suggest pages that could be created (but do not create them automatically — leave that for ingest).