| name | wiki-query |
| description | Use when the user asks any question, requests research, or wants information from the knowledge base. This is the default action in this repository — when in doubt, search the Wiki. Use for "find me...", "what do we know about...", "tell me about...", "who is...", "what is...", or any general research question. |
Knowledge Base - Query
When the user asks any question:
- Search the QMD collection
tomtom, which indexes the whole vault root. Use QMD MCP query/get/multi_get tools when available; otherwise use the qmd CLI (qmd query, qmd get, qmd multi-get). Over-fetch — ask for more candidates than you need (≈12–15) so the recency re-rank below has room to work.
- Retrieve the candidates before answering. Always read each page's
date / date_confidence frontmatter when you retrieve it (QMD ranks by relevance only — it does NOT know about dates).
- Recency re-rank (soft tiebreaker). QMD ordering is pure relevance. Before answering, re-order the candidates yourself:
- Relevance still dominates. Apply only a mild penalty for age, and only as a tiebreaker among results of similar relevance — prefer the page with the newer
date.
- Never drop the only source on a topic just because it is old, and don't penalise low-relevance-but-unique evidence.
- Skip the penalty for historical questions ("what was the original…", "who led X in 2015", "history of…") — there, old pages are the right answer.
- When two candidates cover the same fact, lead with the newer one and note the older as historical.
- If QMD returns no results, fall back to reading
wiki/<type>/_index.md directly, or wiki/index.md for top-level navigation.
- Synthesize an answer with citations. A wikilink target is the note's exact filename, with spaces — never slugified or hyphenated. Body text uses bare links (
[[1-N Device Association]], [[Sensor Data Platform]]); index-style or cross-type references use the vault path ([[wiki/systems/Sensor Data Platform]]). Do not convert spaces to hyphens: [[Sensor-Data-Platform]] is wrong and will not resolve. Only keep hyphens that are part of the real filename ([[Cost-Aware Model Routing]], [[Real-Time Map]]). When unsure of the exact title, prefer the filename as returned by QMD rather than reconstructing it.
Freshness awareness (IMPORTANT)
This Wiki was built from notes going back to ~2006, so it mixes current and long-outdated information. Both wiki pages and raw/ source pages carry freshness metadata in frontmatter — always read it and weigh it before trusting a claim:
date: YYYY-MM-DD — the page's content date. For a wiki page, the newest source feeding it (best "as of" signal); for a raw page, the artifact's own date.date_span: YYYY or YYYY–YYYY — a wide span means the page mixes eras; old and new facts sit side by side.date_confidence: high | medium | low — low means the date is only a capture/ingestion date (e.g. an old document scanned recently) and may overstate freshness; treat such dates skeptically.
Rules when answering (today's date is available in context):
- Surface the date. State the "as of" date for time-sensitive facts: "As of 2024 (per the page's
date)…". Never present dated info as if it were necessarily current.
- Flag stale data. If
date is more than ~2–3 years old, explicitly warn that it may be outdated and worth verifying — especially for org structure, people's roles, projects, systems, and decisions.
- Prefer newer on conflict. When two pages/sources disagree, trust the one with the more recent
date and say which you chose and why. Note status: superseded / deprecated pages as historical.
- Distrust low confidence. For
date_confidence: low, caveat that the date is uncertain.
- Call out era-mixing. For a wide
date_span, separate "historically" from "more recently" rather than blending them.
- Unknown freshness. If a page has no
date field, its recency is unknown — say so rather than assuming it is current.
Prefer recent sources when gathering evidence, but don't discard old pages — they're valuable for history, just label them as such.
Block provenance and query-time freshness
Some canonical Wiki pages now carry block-level provenance:
- Claim paragraphs use stable Obsidian block IDs such as
^claim-owner-01.
- A page-level
> [!provenance] callout with schema: kb-prov-v1 maps block IDs to sources, observed, checked, status, confidence, superseded_by, and contradiction metadata.
scripts/system/wiki-provenance-lint.py validates that metadata.scripts/system/wiki-freshness-inventory.py builds a read-only inventory of canonical blocks and raw notes.scripts/system/wiki-drift-detect.py finds pages that likely need one-page curation.scripts/system/wiki-freshness-query.py turns retrieved page paths into a query-time packet of ranked blocks, raw-note mappings, raw evidence, and legacy-page warnings.scripts/lib/freshness_rank.py contains deterministic helpers for ranking block lists by current/history/change query intent.
For current, recent, policy, people, project, system, cost, customer, or otherwise freshness-sensitive questions, build the freshness packet automatically after retrieval. Do not ask the user to remember the script.
When retrieved pages contain kb-prov-v1 or the question is freshness-sensitive:
- Build a freshness packet after retrieval. Run
python3 scripts/system/wiki-freshness-query.py --query "<user query>" --page "<retrieved page>" ... --format json over the retrieved page paths. If candidate pages have not already been collected, run python3 scripts/system/wiki-freshness-query.py --query "<user query>" --qmd --format json; it can run QMD discovery first, resolve returned Wiki pages, map returned raw notes to canonical pages through wikilinks/title matches, and keep unmapped raw hits as raw_evidence.
- Answer from blocks, not whole pages. Prefer packet blocks with
freshness_action: prefer, status: current, recent checked, and confidence: high|medium.
- Use minimal stamps as cautions.
freshness_action: use-as-page-caution means the page has only a page-level migration stamp; use the block text to qualify the answer, but do not treat the rest of the page as fully block-verified.
- Rank lower, explain, don't erase.
stale, historical, and disputed blocks may still be useful, but should not silently win current-state answers.
- Confirmed supersession is strongest. A block with
status: superseded or superseded_by must not be used as the main current answer unless the user asks for history.
- Use raw notes as evidence.
raw_mappings explain which raw hits pulled in canonical pages. raw_evidence contains relevant raw hits that do not yet map to a canonical page; mention them as uncategorized evidence instead of treating the query as evidence-free.
- Explain only when it matters. If freshness affects confidence, say why: "The canonical block is unchecked, and newer raw notes mention the topic" or "Older evidence is superseded by block X."
For freshness-sensitive questions where the retrieved page has no block provenance yet, treat it as a legacy page: use ordinary date/frontmatter rules, then mention if newer raw notes or drift candidates make the answer uncertain.
Supersession (explicit replacements)
Some pages are explicitly marked as replaced by a newer page via frontmatter:
superseded_by: [[wiki/...]] — this page is historical; the linked page is its replacement.supersedes: [[wiki/...]] — this page replaces an older one.
When a retrieved page has superseded_by:
- Follow the link (and any chain — A→B→C) to the newest live page and answer from that, not the superseded one.
- Use the superseded page only for history ("Previously X did this until ~2022; it was superseded by [[New Thing]]"). Never present superseded content as the current state.
- If the user explicitly asks about the old thing or its history, describe it and note it's superseded.
This is a stronger signal than date: a superseded page may still be recent, but it has been deliberately retired.
Follow-up:
- If the answer seems to be a valuable artifact (analysis, full recap, comparison, non-obvious connection between pieces of information), propose filing it as a new page in
wiki/conversations/ and updating the index. In that case, the title of the new page should be descriptive and include the date, e.g. wiki/conversations/YYYY-MM-DD Descriptive Page Title For Discussion.md.
- Include the page in the index, with a one-liner summary of the content.
