kb-query

KB Query

Search, answer, and generate outputs from the approved live layer.

Minimal loop

locate the best approved live pages and briefings
answer or draft the artifact from wiki/live/
archive the result when it is substantive
record the smallest durable delta that would improve the wiki next

When this compounds the wiki

kb-query should not behave like disposable chat over live notes. Strong outputs should either become reusable archived artifacts or leave behind explicit candidates for a better concept page, synthesis page, relationship edge, governed question, or curated hub.

When not to promote

Do not treat a polished answer as approved truth by itself. If the result discovers durable knowledge, it must still re-enter through draft -> review -> live.

Read before querying

Read these files first:

local AGENTS.md
local CLAUDE.md if present
../obsidian-notes-karpathy/scripts/skill-contract-registry.json
../obsidian-notes-karpathy/references/file-model.md
../obsidian-notes-karpathy/references/lifecycle-matrix.md
../obsidian-notes-karpathy/references/briefing-template.md
../obsidian-notes-karpathy/references/qa-template.md
../obsidian-notes-karpathy/references/content-output-template.md
../obsidian-notes-karpathy/references/activity-log-template.md
../obsidian-notes-karpathy/references/search-upgrades.md
../obsidian-notes-karpathy/references/questions-and-reflection-policy.md
../obsidian-notes-karpathy/references/query-writeback-lifecycle.md
../obsidian-notes-karpathy/references/memory-lifecycle.md
../obsidian-notes-karpathy/references/graph-contract.md
../obsidian-notes-karpathy/references/render-template.md
../obsidian-notes-karpathy/references/profile-contract.md
../obsidian-notes-karpathy/references/episode-template.md

Treat skill-contract-registry.json as the canonical source for required references, baseline script, and expected write surfaces.

If ../obsidian-notes-karpathy/scripts/scan_query_scope.py exists, run it first and treat its output as the deterministic baseline for live-layer retrieval boundaries.

Then start with:

wiki/index.md
wiki/live/indices/INDEX.md
wiki/live/indices/CONCEPTS.md
wiki/live/indices/SOURCES.md
wiki/live/indices/TOPICS.md when present
wiki/live/indices/QUESTIONS.md when present
relevant wiki/briefings/{role}.md when the request maps to a role
prior outputs/qa/

Hard boundary

kb-query must not treat raw/ or wiki/drafts/ as retrieval truth.

MEMORY.md is also outside the default knowledge retrieval boundary. Read it only when the user is asking about preferences, editorial priorities, or collaboration behavior rather than topic knowledge.

Those layers may be cited only as evidence if a human explicitly asks for source inspection. Default synthesis should stay on wiki/live/. outputs/episodes/ and outputs/health/graph-snapshot.json may help surface candidates, but they are not default truth surfaces.

Source-backed answer discipline

prefer approved summaries when grounding key conclusions
use concept and entity pages as navigation and synthesis aids, not as a shortcut around approved evidence trails
when sources disagree, say so explicitly instead of flattening the disagreement

Modes

search mode for quickly locating approved pages and ranking local candidates before synthesis
research mode for grounded answers archived into outputs/qa/
web mode for static browseable web exports under outputs/web/
reflect-lite mode for question resolution, synthesis notes, or gap reports that should stay outside live until re-reviewed

When a substantive answer or artifact creates durable follow-up work, archive explicit writeback_candidates, open_questions_touched, source_live_pages, writeback_status, and a followup_route so the next compile/review or maintenance pass can decide what should happen next.

Prefer the smallest durable delta that improves future reuse:

update an existing live concept or entity when the identity is already right
draft a missing concept, entity, or synthesis when the knowledge is durable but absent
strengthen related links or question tracking when the problem is graph quality rather than page absence
create or expand a curated hub when repeated outputs keep traversing the same approved cluster

Retrieval ladder

Default retrieval order:

wiki/index.md
wiki/live/indices/*
governance indices such as QUESTIONS.md, GAPS.md, and ALIASES.md when present
relevant wiki/briefings/{role}.md
prior outputs/qa/
local structured or metadata-driven search
optional semantic retrieval only as candidate surfacing

Semantic retrieval may help discover candidate pages, but approved live pages remain the truth source.

If the user explicitly says kb-search, treat that as direct wording for kb-query search mode.

If the user wants slides, reports, charts, or canvas derivatives from approved knowledge, hand off to kb-render instead of stretching kb-query into deterministic rendering work.

Writeback contract

Compounding principle: every substantive query should leave the wiki at least slightly better — whether through a new draft page, a stronger relationship, an updated hub, or a promoted question. Writeback is the default posture, not an opt-in extra.

Use ../obsidian-notes-karpathy/references/query-writeback-lifecycle.md as the detailed contract.

At minimum, substantive Q&A or publish outputs should:

record source_live_pages when specific approved pages grounded the answer
record open_questions_touched when the answer materially advances or reframes a standing question
record writeback_candidates when the output discovers durable follow-up worth re-entering the wiki
record writeback_status so later passes can see whether the work is still pending
record compounding_value when future reuse, navigation value, or synthesis payoff should be explicit
record crystallized_from_episode when the output came out of a broader episodic chain
set followup_route to none, draft, or review

Use:

none when the output is grounded and does not create durable follow-up work
draft when the output suggests new or updated long-term knowledge that must re-enter draft -> review -> live
review when the next action is an immediate human decision or a governance pass on already-prepared maintenance work

Output to the user

Report:

which live pages and briefings were used
whether prior Q&A was reused
where the new artifact was saved
whether a query or publish log entry should be appended
whether any follow-up should go back into drafts instead of directly mutating live