query

Skill: query

WHAT

Purpose and context

Purpose: Answer question by synthesizing wiki knowledge. Valuable findings not in wiki become new pages, compounding knowledge over time.
Trigger (when to invoke): When user asks question requiring synthesis across multiple wiki pages or raw sources; or when needing to know "what is the basis", "which edge to cite", "path in the graph", "cite evidence".
Non-goals: do not answer with knowledge outside wiki/raw/ (do not fabricate facts); do not ingest the whole source yourself (gap → call ingest); do not edit a page's drift flag (that is the job of /lint/wiki-sync).

Mental model

câu hỏi → Tầng 0 mem-rank (episodic) → Tầng 1 rg xếp hạng theo độ phủ term → Tầng 2 Read full top-N → Tầng 3 wikilinks → cổng drift → tổng hợp → [trang wiki mới nếu insight mới] → log + telemetry → Evidence (eid cạnh).

Input and output contract

	Field	Required?	Meaning
In	question	yes	requires synthesizing multiple wiki pages / raw
Out	answer	yes	warning `⚑ CẢNH BÁO DRIFT` (if any) placed at the start of the answer
Out	section `## Evidence`	yes	eid of edges actually backing it, or `Evidence: none (page-level only)`
Out	new wiki page + index + log	only when there is a new insight	concept or source
Out	line `wiki/log.md` + record `query-log.py`	yes	log `## YYYY-MM-DD — query — <question summary>`; telemetry fail-open
Out	output report draft	yes (unless 0 artifacts)	Delivery section

Rules and capabilities

RULE-01 (MUST): OKF v0.1 (R9): any new wiki page starts with a YAML frontmatter block (---) with a non-empty type; copy the matching _template.md and keep the ## Origin section.
RULE-02 (MUST): Never invent facts. Synthesize from wiki and raw/ only.
RULE-03 (SHOULD): Query revealing gap (missing entity, missing concept) should trigger ingest of relevant raw/ source if one exists.
RULE-04 (MUST): Progressive disclosure — DO NOT load the whole page in step 1; only Read full top-N.
RULE-05 (MUST): Drift warning must be carried verbatim into the answer — do not swallow, do not refuse to answer.
Capabilities: read wiki + raw/ + episodic memory layer + wiki graph; write new wiki pages, index, log, telemetry. Code-graph for questions about code.

Failure boundaries

Wiki and raw/ have no information → state clearly that there is no basis (partial), do not fabricate.
No edge backs it → Evidence: none (page-level only).
Page read flagged as drift → still answer, with a warning at the start of the answer.
Tier 0 script / drift / telemetry error → fail-open, skip that step, do not break the session.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	question	Tier 0 `mem-rank.py retrieve`	top-k memory/episode	NOOP → skip
W02	deterministic	question	Tier 1 `rg` rank by term coverage (code → `search_symbols`)	slug list	—
W03	effect	top-N	Tier 2 Read full top-N (~5); Tier 3 follow wikilinks if needed	page content	—
W04	deterministic	slug read	Drift gate `wiki-sync.py --flags-for`	warning or silence	always exit 0
W05	judgment	content	Missing → check `raw/`; synthesize and answer	answer	no basis → partial
W06	judgment	answer	New insight? → create page + index + log	new page / skip	no → skip
W07	effect	result	Log `wiki/log.md` + telemetry `query-log.py --record`	log + record	fail-open
W08	deterministic	basis page	`wiki-graph.py cite <page>` → item `## Evidence`	edge eid	none → page-level only

Details of each step (source of truth for W01–W08):

Steps — progressive disclosure 3 tiers (DO NOT load the whole page at step 1)

Principle: scan CHEAPLY to rank first, only READ FULL a few high-scoring pages. Measured on the golden set wiki/sources/evals/retrieval/ shows this keeps recall intact while cutting ~65% tokens compared to "read every matching page" (baseline L0). Verification: retrieval-eval.py --check.

Tier 0 — SEMANTIC retrieval (episodic + memory), NOT just by link: before scanning the wiki, ask the episodic memory tier whether previous session has already touched this question: python3 harness/scripts/mem-rank.py retrieve "<câu hỏi>" --k 5 (add --kind-filter episode to fetch only session events). Return top-k relevant memory/episode by meaning (token-overlap, will be embedding when adapter mem-rank.config.yaml is wired) — catches pages that do NOT have [[wikilink]] points to. NOOP (empty) then skip, do not stuff noise. Use this result to seed the page list for Tier 1 + know "which session this was once done in".
Tier 1 — scan, do NOT open any full page: ripgrep the question above wiki/index.md + wiki content (rg -c '<term>' wiki/ to count matches), rank pages by term coverage (page containing the most terms of the question). Question about code → use the code-graph MCP (search_symbols) instead of rg. Result of this tier = list of slugs + matching lines; not yet Read any full page.
Tier 2 — drill: only Read FULL top-N highest-scoring pages (default ~5). Drop the tail of the ranking — do not read "just to be sure".
Tier 3 — context: if the answer needs a related thread, follow the [[wikilinks]] of the pages just read (equivalent to engram's timeline/related) — still only open pages that are pointed to, do not open all. 3b. Drift gate on the READ path (0 token, fail-open) — before synthesizing, ask whether the page just read is drifting from the code: RUN: python3 harness/scripts/wiki-sync.py --flags-for "<slug1,slug2,…>" (downstream does not have harness/ in the repo then use the global version: python3 ~/.claude/harness/harness/scripts/wiki-sync.py --flags-for "…" --root .). Pass exactly the pages that were Read in tiers 2–3. The command always exits 0; silence = no page is flagged. If there is a line ⚑ CẢNH BÁO DRIFT → copy that warning verbatim into the answer (one line per page, placed right at the start of the answer section) then answer normally; do not swallow the warning, and do not refuse to answer. Why this step exists: wiki-sync --check writes the flag code-drift into stale.json, but before 2026-07-19 only /lint read that flag — and lint runs periodically, so between two lint runs /query returns a page that has drifted from the code without warning about anything. That is exactly the case of "the wiki is the source of truth but the content has drifted" that makes the model reason confidently on old knowledge.
If answer needs info not in wiki, check raw/ for unprocessed sources.
Synthesize and answer directly.
Evaluate: does answer contain non-obvious insight, connection, or conclusion not already in wiki?
- If yes: create new wiki page (concept or source), update wiki/index.md, log in wiki/log.md.
- If no: skip.
Append to wiki/log.md: ## YYYY-MM-DD — query — <question summary> with note on whether new page created.
Telemetry (measures RETRIEVAL — fail-open): after answering, record the query so retrieval effectiveness is measurable: python3 harness/scripts/query-log.py --record --question "<câu hỏi>" --pages "<slug1,slug2>" --tokens <ước tính token đã đọc> --tier <1|2|3> --pages = the wiki pages actually read; --tier = deepest layer reached (1 scan / 2 full reads / 3 wikilinks). Script is fail-open — never breaks the session. Known limitation: only measures when the skill query is invoked, not when the model Reads directly.
Evidence — cite edges, not just pages. For EACH wiki page used as evidence, run: python3 harness/scripts/wiki-graph.py cite <page> then attach the item ## Evidence at the end of the answer, listing eids of the edges that actually support the conclusion — do not list an edge just because it exists:
```
## Evidence
- e:4b65f8c5  concepts/decision-anchoring.md -> concepts/adapt-modes.md  (wikilink)
- e:988aa19d  index.md -> concepts/example-concept.md  (mdlink)
```
No supporting edge → state outright Evidence: none (page-level only). More honest than fabricating a path. An edge with type (supports/contradicts/supersedes/derives-from/depends-on) declared in the frontmatter relations: of the page is stronger than a bare wikilink because it states the relationship CLEARLY.

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	conditional_required	question about code	use code-graph MCP (`search_symbols`) instead of `rg` in Layer 1	—	W03
B02	conditional_required	there is a line `⚑ CẢNH BÁO DRIFT`	copy verbatim to the top of the answer	silent → skip	W05
B03	conditional_required	downstream has no `harness/` in the repo	use the global version `~/.claude/harness/harness/scripts/wiki-sync.py --root .`	—	W05
B04	conditional_required	the answer has a new insight not in the wiki	create concept/source page + index + log (OKF)	no → skip	W07
B05	conditional_required	the query exposes a gap and there is a source `raw/` related	call `ingest` that source	no source → record the gap	W07

Validation and stopping

Deterministic: retrieval-eval.py --check measures recall/token of progressive disclosure; wiki-graph.py cite generates real eids. Judgment: synthesize and evaluate "new insight". Stop after W08 + Delivery; do not open extra pages beyond top-N "to be safe".

Examples

Positive: "why does adapt-modes split into 3 absorb types?" → rg ranks, Read concepts/adapt-modes.md + 2 high-score pages, drift silent → answer + ## Evidence list e:4b65f8c5 concepts/decision-anchoring.md -> concepts/adapt-modes.md (wikilink); no new insight → do not create a page.
Boundary/failure: a read page has the code-drift flag → the answer begins with the line ⚑ CẢNH BÁO DRIFT verbatim, then answers; no supporting edge → Evidence: none (page-level only).

Delivery — Output Report

After all main skill tasks are complete, write a propose draft to the wiki.

Steps

1. Build the filename:

Format: DDMMYY-<ten>.md
DDMMYY = today (e.g., 020626 for 2 June 2026)
<ten> = 2–4 kebab-case words summarising what was done (e.g., landing-page-coteccons, brand-kit-fintech, ingest-auth-spec)

2. Write llmwiki/wiki/sources/draft/DDMMYY-<ten>.md:

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. Update wiki index & log:

llmwiki/wiki/index.md — append one row: | [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
llmwiki/wiki/log.md — append: ## YYYY-MM-DD — <skill-name> — <ten>

Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like /caveman-stats).