From 91e643553ed78de0b3383a74492ed0a15c579254 Mon Sep 17 00:00:00 2001
From: Steve Beaulac <steve@beaulac.me>
Date: Mon, 22 Jun 2026 23:06:03 -0400
Subject: [PATCH] feat(pkm): add compiled wiki layer, packet promotion, and
 retrieval checks to research skills

- Add compiled wiki maintenance, retrieval lint, and packet promotion
  steps to knowledge-gardener skill
- Restructure research-vault workflow with source ingest, answer filing,
  and pre-completion lint pass
- Add Log.md for tracking ingest, queries, and corrections
- Enhance Claims template with provenance, supports/contradicts, and
  confidence tracking
- Add Compiled Pages table and Raw Source Rules to packet template
- Enhance atomic notes with frontmatter, promotion status, and
  structured links
- Distinguish source claims, synthesis, user opinions, and open
  questions throughout

This implements a Karpathy-style compiled wiki approach where raw
sources stay immutable, packet notes are the maintained synthesis
layer, and reusable notes can be promoted to the main vault.
---
 common/pkm/knowledge-gardener/SKILL.md        | 22 +++++++-
 common/pkm/research-vault/SKILL.md            | 30 ++++++++---
 .../references/research-packet-template.md    | 52 +++++++++++++++++--
 3 files changed, 93 insertions(+), 11 deletions(-)

diff --git a/common/pkm/knowledge-gardener/SKILL.md b/common/pkm/knowledge-gardener/SKILL.md
index 3471565..50840cd 100644
--- a/common/pkm/knowledge-gardener/SKILL.md
+++ b/common/pkm/knowledge-gardener/SKILL.md
@@ -61,10 +61,26 @@ project: ""
 
 7. Research Capture
    - Store source summary in vault.
-   - Extract key claims, evidence, and follow-up questions.
+   - Extract key claims, evidence, confidence, and follow-up questions.
+   - Distinguish raw source claims, agent synthesis, user opinions, and open questions.
    - Convert durable insights into permanent notes.
 
-8. Zettelkasten Conversion
+8. Compiled Wiki Maintenance
+   - For bounded research topics, maintain a Karpathy-style compiled wiki layer: immutable raw sources → maintained concept/claim/synthesis notes → retrievable answers.
+   - On ingest, update existing pages before creating duplicates; the graph should get denser, not just larger.
+   - File durable query answers back into notes, then add or update links from indexes/MOCs.
+   - Keep a lightweight log of ingests, filed answers, lint passes, promotions, and major corrections when the folder has a `Log.md` or equivalent.
+
+9. Retrieval Lint
+   - Check for unsupported claims, stale or contradictory claims, orphan notes, missing backlinks, missing glossary terms, and unanswered questions.
+   - Verify a future agent can answer the main question from the maintained notes without rereading raw sources.
+
+10. Packet Promotion
+   - Treat research packets as incubators and the main vault as the indexed library.
+   - Promote notes only when they are reusable beyond the packet, stand alone, have evidence/provenance, and connect to existing vault concepts.
+   - Leave a link behind in the packet and update relevant indexes/MOCs.
+
+11. Zettelkasten Conversion
    - Convert source note into atomic permanent notes.
    - Add explicit links and one short structure note (MOC-lite) when useful.
 
@@ -74,6 +90,8 @@ project: ""
 - Prefer additive edits and clear section boundaries.
 - Keep writing concise and skimmable.
 - Keep tags focused and reusable.
+- Keep citations close to claims; do not let synthesized notes obscure source provenance.
+- Before finalizing research edits, run a retrieval check: likely future questions should have obvious entry points through indexes, links, claims, or glossary terms.
 - Rebuild semantic index after major note creation/refactor sessions.
 
 ## Operational Commands
diff --git a/common/pkm/research-vault/SKILL.md b/common/pkm/research-vault/SKILL.md
index be025fe..bee1bbb 100644
--- a/common/pkm/research-vault/SKILL.md
+++ b/common/pkm/research-vault/SKILL.md
@@ -10,7 +10,7 @@ Use when the user wants to learn or research a topic conversationally and save t
 
 ## Packet
 
-Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic>/`, containing all notes from the run: `Index.md`, `Sources.md`, `Synthesis.md`, `Claims.md`, `Questions.md`, `Conversation.md`, `Glossaries.md`, and any atomic notes. Load `references/research-packet-template.md` before writing packet files or when exact structure matters.
+Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic>/`, containing all notes from the run: `Index.md`, `Sources.md`, `Synthesis.md`, `Claims.md`, `Questions.md`, `Conversation.md`, `Glossaries.md`, `Log.md`, and any atomic notes. Treat the packet as a Karpathy-style compiled wiki for the topic: raw sources stay immutable, packet notes are the maintained synthesis layer, and this skill is the schema. Load `references/research-packet-template.md` before writing packet files or when exact structure matters.
 
 ## Workflow
 
@@ -18,11 +18,14 @@ Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic
 2. **Frame the goal.** Ask one question at a time until you can restate the topic, learning objective, scope, and success criteria. Discover the user's goal, prior knowledge, intended use, depth, constraints, output preference, and trusted/distrusted sources only as needed.
 3. **Create or defer the folder.** Create the packet folder once the topic has a stable working title; if still vague, keep conversing. Before writing durable notes, every artifact must have a path inside the packet folder.
 4. **Map context.** Search the vault for the topic, synonyms, projects, and neighboring concepts. Read enough relevant notes to make meaningful links, not keyword matches.
-5. **Research and teach.** Answer the user directly, explain findings in small chunks, cite claims, preserve uncertainty, share resources when they improve learning or evidence quality, and correct misunderstandings before moving on.
-6. **Check understanding and completeness.** Ask one diagnostic or completeness question per turn. Answer follow-ups with evidence, examples, counterarguments, implementation details, or resources as needed. Capture unresolved gaps in `Questions.md`.
-7. **Write incrementally.** For long sessions, update `Conversation.md`, `Questions.md`, `Glossaries.md`, and `Sources.md` as the work progresses. By the end, no research, teaching insight, user question, glossary term, source, or durable knowledge should exist only in chat.
-8. **Link into the vault.** Add wikilinks from packet notes to relevant existing notes; suggest backlinks instead of editing unrelated existing notes unless the user asked for full integration.
-9. **Report.** Summarize the packet path, files changed, links or backlink suggestions, top takeaways, what the user now understands, and remaining questions.
+5. **Ingest sources into claims.** For each source, preserve its path in `Sources.md`, extract evidence-backed claims into `Claims.md`, update affected concept/summary pages, and append an event to `Log.md`. Completion: every non-trivial factual claim has source, evidence, confidence, and at least one related link or explicit note that no link exists yet.
+6. **Research and teach.** Answer the user directly from the compiled packet when possible, explain findings in small chunks, cite claims, preserve uncertainty, share resources when they improve learning or evidence quality, and correct misunderstandings before moving on.
+7. **File good answers.** When a query produces a durable synthesis, decision, comparison, or explanation, add it back into `Synthesis.md`, `Claims.md`, or an atomic note instead of leaving it only in chat. Append the query and filed destination to `Log.md`.
+8. **Check understanding and completeness.** Ask one diagnostic or completeness question per turn. Answer follow-ups with evidence, examples, counterarguments, implementation details, or resources as needed. Capture unresolved gaps in `Questions.md`.
+9. **Write incrementally.** For long sessions, update `Conversation.md`, `Questions.md`, `Glossaries.md`, `Sources.md`, and `Log.md` as the work progresses. By the end, no research, teaching insight, user question, glossary term, source, or durable knowledge should exist only in chat.
+10. **Lint the packet.** Before final report or promotion, check for unsupported claims, stale or contradictory claims, missing source links, orphan atomic notes, glossary terms without links, unanswered questions, and missing backlinks from `Index.md`. Record notable lint findings or fixes in `Log.md`.
+11. **Promote reusable notes.** If a packet note becomes broadly useful beyond the run, propose promotion to the main vault, copy or move only with user approval, leave a provenance link in the packet, and update relevant indexes/MOCs.
+12. **Report.** Summarize the packet path, files changed, links or backlink suggestions, top takeaways, what the user now understands, remaining questions, lint status, and promotion candidates.
 
 ## Conversation Rules
 
@@ -36,6 +39,11 @@ Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic
 
 ## Capture Rules
 
+- Keep raw sources immutable: do not edit copied articles, PDFs, transcripts, or source exports except to add separate metadata notes.
+- Distinguish source claims, agent synthesis, user opinions, and open questions with headings or labels.
+- Write claims as answerable units, not vague topics: one sentence that can be supported, contradicted, or revised.
+- For every claim, include evidence, source, confidence, implications, and related notes; use `low` confidence when provenance is weak or the claim is inferred.
+- Prefer updating existing packet pages over creating duplicates; new sources should make the packet denser, not merely bigger.
 - Put every acronym, abbreviation, domain-specific phrase, specialized term, jargon term, and piece of domain nomenclature in `Glossaries.md`, even when explained elsewhere.
 - Keep sources, synthesis, claims, questions, conversation, glossary, and atomic knowledge separate.
 - Keep citations close to claims; mark confidence when evidence is incomplete or contested.
@@ -43,6 +51,16 @@ Create one vault folder per research run, normally `Research/<YYYY-MM-DD> <Topic
 - Distinguish source claims from interpretation; record failed searches or missing evidence when they affect the conclusion.
 - Create atomic notes in the packet folder for durable concepts; link each from `Index.md` and back to its source or synthesis section.
 
+## Retrieval Checks
+
+Run these checks before treating the packet as complete:
+
+- Could a future agent answer the user's main question from `Index.md`, `Synthesis.md`, and `Claims.md` without rereading raw sources?
+- Does `Index.md` point to every durable packet page with enough context to choose the right page?
+- Are important terms findable in `Glossaries.md` and linked from the pages that use them?
+- Are contradictions, uncertainty, and missing evidence visible near the relevant claims?
+- Does `Log.md` show the ingest/query/lint history well enough to reconstruct what changed and why?
+
 ## Linking Rules
 
 Use Obsidian wikilinks: `[[Note Title]]` or `[[path/to/Note|alias]]`. Add links only when they explain context: broader concepts, projects, areas, MOCs, sources, authors, methods, tools, domains, supporting/refining/contradicting claims, or active problems. Do not link on shared words alone.
diff --git a/common/pkm/research-vault/references/research-packet-template.md b/common/pkm/research-vault/references/research-packet-template.md
index 43b74e5..88389ce 100644
--- a/common/pkm/research-vault/references/research-packet-template.md
+++ b/common/pkm/research-vault/references/research-packet-template.md
@@ -24,10 +24,16 @@ Use inside `Research/<YYYY-MM-DD> <Topic>/` unless the vault has a clearer conve
 - [[Questions]]
 - [[Conversation]]
 - [[Glossaries]]
+- [[Log]]
 
 ## Related Vault Notes
 -
 
+## Compiled Pages
+| Page | Type | One-line purpose | Source basis | Status |
+|---|---|---|---|---|
+|  | source summary \| concept \| claim cluster \| synthesis \| promoted |  |  | draft \| reviewed \| promoted |
+
 ## Open Questions
 -
 ```
@@ -43,6 +49,10 @@ Use inside `Research/<YYYY-MM-DD> <Topic>/` unless the vault has a clearer conve
 
 ## Notes
 -
+
+## Raw Source Rules
+- Preserve raw source files as immutable evidence.
+- Add interpretation in packet notes, not inside the source file.
 ```
 
 Include source links, books, papers, docs, videos, examples, search terms, or relevant vault notes only when they improve learning or evidence quality.
@@ -71,12 +81,16 @@ Include source links, books, papers, docs, videos, examples, search terms, or re
 ```markdown
 # Claims
 
-## Claim: <claim>
+## Claim: <single answerable claim>
+- Type: source claim | synthesis | opinion | open question
 - Evidence:
 - Source:
 - Confidence: high | medium | low
+- Supports:
+- Contradicts or complicates:
 - Implications:
 - Related notes:
+- Last checked:
 ```
 
 ### `Questions.md`
@@ -118,6 +132,22 @@ Include source links, books, papers, docs, videos, examples, search terms, or re
 
 Record important answers, corrections, and scope decisions as the session progresses.
 
+### `Log.md`
+
+```markdown
+# Log
+
+Append one entry for each ingest, query filed back into the packet, lint pass, promotion, or major correction.
+
+## YYYY-MM-DD HH:MM — <ingest | query | lint | promotion | correction>
+- Input:
+- Files read:
+- Files changed:
+- Claims added or revised:
+- Links added:
+- Open issues:
+```
+
 ### `Glossaries.md`
 
 ```markdown
@@ -136,14 +166,30 @@ Add every acronym, abbreviation, domain-specific phrase, specialized term, jargo
 ## Atomic note
 
 ```markdown
+---
+id: <stable-id>
+aliases: []
+tags: [research, atomic-note]
+area: <area>
+project: [[<packet topic>]]
+---
 # <Concept>
 
 ## Idea
+<State the single reusable concept.>
 
 ## Why it matters
+<Explain retrieval, decision, or learning value.>
 
 ## Evidence or source
+- Claim: [[Claims#Claim <anchor or short title>]]
+- Source:
 
-## Related notes
--
+## Links
+- Broader:
+- Related:
+- Contrasts:
+
+## Promotion status
+- Packet-local | candidate for main vault | promoted to [[path/to/promoted note]]
 ```