From 59447c7a535b42ba2f5c46fa9d8e4360d7d968ba Mon Sep 17 00:00:00 2001 From: karitham Date: Wed, 26 Aug 2026 12:07:51 +0200 Subject: [PATCH] skills: knowledge-query skill --- modules/opencode/agents/pair.md | 37 ++------ .../opencode/skills/knowledge-query/SKILL.md | 90 +++++++++++++++++++ 2 files changed, 96 insertions(+), 31 deletions(-) create mode 100644 modules/opencode/skills/knowledge-query/SKILL.md diff --git a/modules/opencode/agents/pair.md b/modules/opencode/agents/pair.md index b845670..151722c 100644 --- a/modules/opencode/agents/pair.md +++ b/modules/opencode/agents/pair.md @@ -22,35 +22,10 @@ If the request is ambiguous, ask targeted questions, then proceed. - Brief by default. No filler, no restating my question, no "great question". - Kaomojis at the start of answers carry tone nuance — use them. -# Two postures +# Habits -You alternate between two phases. Announce transitions out loud: -"switching to contraction — here's the plan." This lets me veto the seam. - -## Expansion - -Trigger when: scoping, planning, debugging-under-uncertainty, ~3 consecutive -failures on the same approach, "let's think about", ambiguous requests, or -when scope balloons mid-contraction. - -- Read before asking. Always. -- Check skill trigger keywords first; load any potentially-relevant skill. -- Dispatch the `explore` subagent for broad codebase scans — don't glob the - disk yourself. Use purpose-built tools (lsp, grepping rules). -- Ask the smallest set of targeted questions that unblocks a real plan. -- Surface 2-3 options when stakes rise; don't commit to a direction yet. - -## Contraction - -Trigger when: a plan is locked, "implement", "do it", "ship", or executing on -a known step. Finishes by either handing back, dispatching the `review` -subagent for PR review, or doing a small compaction / tightening pass — pick -whichever I signal. - -- BLUF every reply. -- Speed comes from getting it right the first time, not from rushing. -- Be lazy about scope creep: when the task balloons, bounce back to expansion - to confirm we actually want it. -- Slow down only for destructive/irreversible changes (rm, force-push, drop, - schema changes, file overwrites). State what you're about to do, get - confirmation, then act. +- Read before asking. +- Consult the `knowledge-query` skill when a question may be answered + from the notes knowledge base instead of deriving the answer fresh. +- Confirm before destructive or irreversible actions: rm, force-push, + drop, schema changes, file overwrites. diff --git a/modules/opencode/skills/knowledge-query/SKILL.md b/modules/opencode/skills/knowledge-query/SKILL.md new file mode 100644 index 0000000..a6e4367 --- /dev/null +++ b/modules/opencode/skills/knowledge-query/SKILL.md @@ -0,0 +1,90 @@ +--- +name: knowledge-query +description: > + Read-only query protocol for the persistent markdown knowledge base at + ~/notes/wiki. Use when a question may be answered from accumulated + knowledge, for example "what do my notes say about X", "check the wiki", + or "did we settle Y before". Do NOT use for recording, ingesting, or + editing knowledge; dispatch the knowledge-worker agent instead, because + this protocol never writes. +license: MIT +metadata: + author: kar +--- + +# Knowledge base queries + +The Obsidian vault at `~/notes` holds a persistent knowledge base. The curated part lives in `~/notes/wiki`; everything else in the vault is human-written evidence. Both are readable through this protocol. Neither is writable through it. + +## Parameters + +- **question** (required): stated by the user or implied by the task. +- **scope** (optional): one scope directory to search first. Default: search all scopes. + +## Layout + + ~/notes/wiki/ + ├── index.md # catalog: link + one-line summary per page + ├── log.md # append-only operation record, scope-tagged + ├── common/ # context-free knowledge + │ └── entities/ concepts/ sources/ syntheses/ + └── / # one dir per context, same four subdirs + +A scope separates one context from another. Page types: `entities/` holds people, orgs, products, projects; `concepts/` holds ideas, techniques, frameworks, one per page; `sources/` holds one page per ingested source; `syntheses/` holds durable answers, comparisons, overviews. + +Every page starts with YAML frontmatter: `type`, `updated`, `sources`. + +## Steps + +### 1. Orient + +Read `index.md` and the last ~20 lines of `log.md`. The index lists every page with a summary; the log shows recent operations. + +If `wiki/` does not exist, the knowledge base is empty. Report that and stop. + +### 2. Search + +Grep across every scope, not only `common/`. Search the human notes outside `wiki/` as well, because pages cite them as sources. Follow wiki-links between pages; the links connect most of the corpus. + +**Constraints:** + +- MUST NOT restrict the search to one unnamed scope, because matching knowledge often sits in another context. + +### 3. Answer + +State each claim with the path that supports it. Separate what pages state from what was derived, and mark derived statements as inference. + +**Constraints:** + +- MUST NOT state a fact without a citation, because an uncited claim cannot be checked against its source. +- MUST NOT fill a gap with freshly derived guesses; a derivation presented as corpus knowledge misleads later sessions. + +### 4. Report gaps + +When the corpus cannot answer the question, state that plainly and name the missing subject. When an answer is worth keeping, propose dispatching the `knowledge-worker` agent so the result compounds instead of staying session-local. + +## Constraints + +- MUST NOT create, edit, or delete anything under `~/notes`. Writes belong to the knowledge-worker agent, and everything outside `wiki/` belongs to the human. +- SHOULD prefer citing an existing page over restating its content, so answers stay consistent with the corpus. + +## Example + +Input: "what did we decide about ghostty config sharing?" + +1. Orient: `index.md` lists `common/entities/ghostty.md` and a synthesis under `nixos/syntheses/`. +2. Search: grep for `ghostty` across all scopes; the human note `~/notes/journal/2026-03-14.md` surfaces as a cited source. +3. Answer: "Terminal configs are shared through the dotfiles flake, not per-host overrides (`nixos/syntheses/terminal-config.md`, source `~/notes/journal/2026-03-14.md`)." +4. Gap: the corpus records the decision but not why per-host overrides were rejected; report the gap and offer a `knowledge-worker` dispatch. + +Output: a cited answer plus one reported gap. No files changed. + +## Troubleshooting + +### Pages disagree + +Cite both claims with their paths and `updated` dates. Prefer neither; contradiction resolution belongs to the write side, and the human decides. + +### Term appears everywhere but has no page + +Treat it as a recurring-term gap. Report it in the gap step; do not create the page here. -- 2.51.2