akb-query

AKB Query

Answer one question from the target AKB vault. Decompose the question, search the vault with the strategy that fits, ground the answer in the documents found — honoring AKB's compiled-truth-over-timeline precedence — and synthesize a cited answer. Brain-first: the vault is the source of truth, not the model's prior knowledge.

Workflow classification. LLM-wiki Query workflow — the read half only (à la gbrain's query, mutating: false). This skill never writes: no akb_put / akb_update, no promote-to-page. Promoting valuable answers into new pages, consolidation, and dream-cycle maintenance are the external maintenance layer's job over the same vault, not this skill's.

Scope boundaries:

• Read-only. Every tool call reads. The skill answers from vault content and cites it; it does not modify the vault. (It deliberately does not use akb_grep — that verb's replace= mode rewrites matching documents, so it is not read-only; exact-term lookup goes through akb_search, whose hybrid index already includes a keyword/BM25 component.)
• Brain-first, grounded. Answer from the vault, never from general knowledge when the vault has relevant content. If the vault lacks the answer, say so — do not fill the gap with a guess.
• Citations are document-scoped. AKB exposes provenance at the document level, not per claim, so a claim cites [doc-uri, section] — not a sentence-level source.

Arguments

/akb-query {question} --vault {vault_name} [--collection {path}] [--type {type}] [--since DATE] [--period D1~D2]

• {question} (required, positional) — a natural-language question. Phrase it as you would ask a person; hybrid search rewards natural phrasing over keyword soup.
• --vault (required) — target AKB vault name.
• --collection {path} (optional) — scope the search to one collection when the question clearly belongs to it.
• --type {type} (optional) — scope to a document type (decision, reference, task, …) when the question implies one.
• --since DATE (optional, ISO YYYY-MM-DD) — add a freshness axis: cross-check hits against recent vault activity and flag stale ones; surface relevant recent changes.
• --period D1~D2 (optional, ISO dates) — same as --since but bounded to the inclusive range. If both are given, --period wins.

If neither --since nor --period is provided, the freshness axis is skipped entirely.

Prerequisites

• AKB MCP server is accessible.
• --vault {name} provided.

Workflow

Phase 1 — Decompose

Parse --vault. Hard-fail if missing: --vault {name} required. Capture {question} and optional flags.

Classify the question into one or more search strategies — a single question may need several:

Question shape	Strategy	Verb
Conceptual / open-ended ("how does…", "tell me about…", "why…") or exact terms (names, versions, IDs, error strings, code)	hybrid	akb_search
Relational ("what depends on X", "what implements Y", "how is A connected to B")	graph	akb_relations / akb_graph

Pick the minimum set that covers the question. Most questions are hybrid — akb_search is vector + keyword/BM25, so it handles both conceptual phrasing and exact tokens; pass the exact token as the query when the question pins one. Reach for graph only when the question asks about links between documents.

Phase 2 — Search

Issue every selected strategy in a single parallel tool-use block — they are independent. Run only the strategies Phase 1 chose. Exception: when the relational strategy is selected but no anchor URI is known yet, that strategy is not independent — run the hybrid search first to find the anchor, then issue akb_relations / akb_graph in a follow-up block. Never call them with a guessed URI.

• Hybrid — akb_search(query="{question}", vault="{vault_name}", limit=10). For an exact token, pass the token itself as the query — the hybrid index matches it on the keyword/BM25 side. Add collection= / type= from the flags or when the question clearly implies one. Add tags=[…] only if the question names specific tags.
• Relational — when an anchor document is known, akb_relations(uri="{anchor_uri}", direction=…, type=…) for direction- and type-filtered edges (single-hop). For a multi-hop neighborhood, akb_graph(uri="{anchor_uri}", depth=…) (BFS; no direction filter — it returns all edges at each level). If the anchor is not yet known, find it with a hybrid search first.
• Freshness (conditional) — only when --since / --period was given: akb_activity(vault="{vault_name}", since="{start_date}", limit=20). For --period D1~D2, pass since=D1 and drop entries after D2 in Phase 3.

Dedup the combined hits by document URI before Phase 3.

Phase 3 — Ground with source precedence

For the top 3–5 deduped hits, read enough to answer — cheapest read first:

1. akb_drill_down(uri="{uri}", mode="outline") to see the document's structure.
2. Read the compiled-truth (top) sections first via akb_drill_down(uri, section="…") — that is the document's current best understanding. Treat the timeline (bottom) section as supporting evidence, not the headline.
3. akb_get(uri) only when you need the full document.
4. akb_provenance(uri) when the question is about authorship or recency ("who decided…", "when was…") — document-level who/when.

Source precedence when documents conflict (highest authority first):

1. The user's direct statements in this conversation.
2. Compiled truth (top of a document).
3. Timeline entries (bottom of a document).
4. External / general knowledge (lowest — and only when the vault is silent).

Staleness — if a freshness axis was requested, cross-check each hit against akb_activity: mark a hit [stale] when it has not changed within the window, and drop activity entries past a --period upper bound.

Phase 4 — Synthesize & answer

Write a direct answer to the question, grounded in what Phase 3 read:

• Cite every claim as [doc-uri, section]. When a claim rests on several documents, cite all of them.
• Conflicts — when sources disagree, present both with their citations and name the contradiction. Never silently pick one.
• Gaps — if the vault does not answer the question, say so plainly (vault "{vault_name}"에 X에 대한 정보가 없습니다) instead of answering from general knowledge. Offer to broaden the search or browse the vault.
• Staleness — surface [stale] markers next to claims drawn from stale documents.

Response shape:

## {question}

{Direct answer in prose, with inline citations: "According to [research/vector-index, compiled truth], …"}

{If sources conflict: a short "Conflicting sources" note citing both.}

{If a freshness axis was requested and recent changes are relevant:}
### Recent changes ({period label})
- [{doc_uri}] {title} — updated {updated_at}

{If the vault is silent on part of the question:}
### Gaps
- The vault has no information on {X}.

---
*{N} documents consulted in vault "{vault_name}"*

Render {period label} as since YYYY-MM-DD or YYYY-MM-DD~YYYY-MM-DD.

Error Handling

Situation	Response
AKB MCP not accessible	AKB MCP server not accessible. Check your MCP configuration.
--vault not passed	--vault {name} required.
Vault not found	Vault "{vault_name}" not found. Create with mcp__akb__akb_create_vault first.
No hits across every strategy	Flag the gap explicitly, then offer to broaden terms, drop --collection/--type, or browse with akb_browse.
Relational anchor URI unknown	Find the anchor with a hybrid search first; if none is found, answer from hybrid hits and note the missing anchor.
akb_activity fails	Drop the freshness axis only; answer from the search hits and note the skipped staleness check.
--since / --period value is not ISO	Ask the user to restate the date (YYYY-MM-DD) before running.

Tips

• Natural-language questions beat keyword strings — "why did we drop the per-plugin config" beats "config".
• Compiled truth (top of a document) is the answer; the timeline (bottom) is the evidence. Lead with the former.
• For relational questions, name the anchor document — graph traversal needs a starting URI.
• Use akb_browse to explore vault structure when a search returns nothing and you are unsure what exists.
• A temporal cue ("what changed since the release", "recent decisions") is what --since / --period is for — it adds the staleness axis hybrid search alone misses.