Skill: query

WHAT

Purpose và 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; hoặc khi cần biết "căn cứ nào", "trích dẫn cạnh nào", "đường đi trong graph", "cite evidence".
• Non-goals: không trả lời bằng kiến thức ngoài wiki/

  raw/

  (không bịa fact); không tự ingest cả nguồn (gap → gọi

  ingest

  ); không sửa cờ drift của trang (việc của

  /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 và output contract

⚑ CẢNH BÁO DRIFT

## Evidence

Evidence: none (page-level only)

wiki/log.md

query-log.py

## YYYY-MM-DD — query — <question summary>

Rules và 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 — ĐỪNG nạp cả trang ở bước 1; chỉ Read full top-N.
• RULE-05 (MUST): Cảnh báo drift phải được chuyển nguyên văn vào câu trả lời — không nuốt, không từ chối trả lời.
• Capabilities: đọc wiki +

  raw/

  + tầng nhớ episodic + wiki graph; ghi trang wiki mới, index, log, telemetry. Code-graph cho câu hỏi về code.

Failure boundaries

• Wiki và

  raw/

  không có thông tin → nói rõ không có căn cứ (partial), không bịa.
• Không cạnh nào chống lưng →

  Evidence: none (page-level only)

  .
• Trang đọc bị cờ drift → vẫn trả lời, kèm cảnh báo đầu câu trả lời.
• Script tầng 0 / drift / telemetry lỗi → fail-open, bỏ qua bước đó, không gãy phiên.

HOW

Main workflow

mem-rank.py retrieve

rg

search_symbols

wiki-sync.py --flags-for

raw/

wiki/log.md

query-log.py --record

wiki-graph.py cite <page>

## Evidence

Steps — progressive disclosure 3 tầng (ĐỪNG nạp cả trang ở bước 1)

Nguyên tắc: quét RẺ để xếp hạng trước, chỉ ĐỌC FULL vài trang cao điểm. Đo trên bộ golden

wiki/sources/evals/retrieval/

cho thấy cách này giữ nguyên recall mà cắt ~65% token so với "đọc mọi trang khớp" (baseline L0). Kiểm chứng:

retrieval-eval.py --check

.

1. Tầng 0 — truy hồi NGỮ NGHĨA (episodic + memory), KHÔNG chỉ theo link: trước khi quét wiki, hỏi tầng nhớ episodic xem phiên trước đã đụng câu hỏi này chưa:

   python3 harness/scripts/mem-rank.py retrieve "<câu hỏi>" --k 5

   (thêm

   --kind-filter episode

   để chỉ lấy sự kiện phiên). Trả về top-k memory/episode liên quan theo nghĩa (token-overlap, sẽ là embedding khi adapter

   mem-rank.config.yaml

   được wire) — bắt được trang KHÔNG có

   [[wikilink]]

   trỏ tới. NOOP (rỗng) thì bỏ qua, không nhồi nhiễu. Dùng kết quả này để mồi danh sách trang cho Tầng 1 + biết "việc này từng làm ở phiên nào".
2. Tầng 1 — quét, KHÔNG mở full trang nào:

   ripgrep

   câu hỏi trên

   wiki/index.md

   + nội dung wiki (

   rg -c '<term>' wiki/

   để đếm khớp), xếp hạng trang theo độ phủ term (trang chứa nhiều term của câu hỏi nhất). Câu hỏi về code → dùng code-graph MCP (

   search_symbols

   ) thay

   rg

   . Kết quả tầng này = danh sách slug + dòng khớp; chưa

   Read

   full trang nào.
3. Tầng 2 — khoan: chỉ

   Read

   FULL top-N trang cao điểm nhất (mặc định ~5). Bỏ phần đuôi bảng xếp hạng — không đọc cho "chắc".
4. Tầng 3 — bối cảnh: nếu câu trả lời cần mạch liên quan, lần theo

   [[wikilinks]]

   của các trang vừa đọc (tương đương timeline/related của engram) — vẫn chỉ mở trang được trỏ tới, không mở tất cả. 3b. Cổng drift trên đường ĐỌC (0 token, fail-open) — trước khi tổng hợp, hỏi xem trang mình vừa đọc có đang lệch code không:

   RUN: python3 harness/scripts/wiki-sync.py --flags-for "<slug1,slug2,…>"

   (downstream không có

   harness/

   trong repo thì dùng bản global:

   python3 ~/.claude/harness/harness/scripts/wiki-sync.py --flags-for "…" --root .

   ). Truyền đúng các trang đã

   Read

   ở tầng 2–3. Lệnh luôn exit 0; im lặng = không trang nào bị cờ. Có dòng

   ⚑ CẢNH BÁO DRIFT

   → chuyển nguyên văn cảnh báo đó vào câu trả lời (một dòng mỗi trang, đặt ngay đầu phần trả lời) rồi mới trả lời bình thường; đừng nuốt cảnh báo, cũng đừng từ chối trả lời. Vì sao có bước này:

   wiki-sync --check

   ghi cờ

   code-drift

   vào

   stale.json

   , nhưng trước 2026-07-19 chỉ

   /lint

   đọc cờ đó — mà lint chạy theo chu kỳ, nên giữa hai lần lint

   /query

   trả về trang đã lệch code mà không cảnh báo gì. Đó đúng là ca "wiki là nguồn sự thật nhưng nội dung đã lệch" khiến model lập luận tự tin trên tri thức cũ.
5. If answer needs info not in wiki, check

   raw/

   for unprocessed sources.
6. Synthesize and answer directly.
7. 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.
8. Append to

   wiki/log.md

   :

   ## YYYY-MM-DD — query — <question summary>

   with note on whether new page created.
9. Telemetry (đo TRUY HỒI — fail-open): sau khi trả lời, ghi lại query để độ hiệu quả truy-hồi đo được:

   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

   = các trang wiki thực sự đọc;

   --tier

   = tầng sâu nhất chạm tới (1 quét / 2 đọc full / 3 wikilinks). Script fail-open — không bao giờ làm gãy phiên. Giới hạn đã biết: chỉ đo khi skill

   query

   được gọi, không đo lượt model tự Read thẳng.
10. Evidence — trích cạnh, không chỉ trích trang. Với MỖI trang wiki đã dùng làm căn cứ, chạy:

    python3 harness/scripts/wiki-graph.py cite <page>

    rồi đính mục

    ## Evidence

    vào cuối câu trả lời, liệt kê eid của những cạnh thật sự chống lưng kết luận — không liệt kê cạnh chỉ vì nó tồn tại:

    ## Evidence
    - e:4b65f8c5  concepts/decision-anchoring.md -> concepts/adapt-modes.md  (wikilink)
    - e:988aa19d  index.md -> concepts/example-concept.md  (mdlink)

    Không cạnh nào chống lưng → ghi thẳng

    Evidence: none (page-level only)

    . Trung thực hơn bịa một đường đi. Cạnh có kiểu (

    supports

    /

    contradicts

    /

    supersedes

    /

    derives-from

    /

    depends-on

    ) khai trong frontmatter

    relations:

    của trang, mạnh hơn

    wikilink

    trần vì nó nói RÕ quan hệ.

Branches

search_symbols

rg

⚑ CẢNH BÁO DRIFT

harness/

~/.claude/harness/harness/scripts/wiki-sync.py --root .

raw/

ingest

Validation và stopping

retrieval-eval.py --check

wiki-graph.py cite

Examples

• Positive: "vì sao adapt-modes tách 3 kiểu absorb?" → rg xếp hạng, Read

  concepts/adapt-modes.md

  + 2 trang cao điểm, drift im lặng → trả lời +

  ## Evidence

  liệt kê

  e:4b65f8c5  concepts/decision-anchoring.md -> concepts/adapt-modes.md  (wikilink)

  ; không insight mới → không tạo trang.
• Boundary/failure: trang đọc bị cờ code-drift → câu trả lời mở đầu bằng dòng

  ⚑ CẢNH BÁO DRIFT

  nguyên văn rồi mới trả lời; không cạnh nào chống lưng →

  Evidence: none (page-level only)

  .

Delivery — Output Report

Steps

• 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

  )

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)_

• 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

).