From 41d1d48025ede752f84de4aaa870bc8b3a69a192 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Mon, 6 Jul 2026 21:26:46 -0400 Subject: [PATCH 1/2] phase1: update vault-conventions.md with OKF v0.1 spec alignment - Merged OKF + vault frontmatter schema - Standard markdown links (not wikilinks) - Bundle definition with index.md/log.md conventions - Fixed type vocabulary (18 types) - Bundle map for all vault directories - Updated curation heuristics for bundle awareness - Added OKF core principles --- .../references/vault-conventions.md | 173 ++++++++++++++++-- 1 file changed, 153 insertions(+), 20 deletions(-) diff --git a/common/pkm/pkm-curation/references/vault-conventions.md b/common/pkm/pkm-curation/references/vault-conventions.md index c86f8e3..53f533d 100644 --- a/common/pkm/pkm-curation/references/vault-conventions.md +++ b/common/pkm/pkm-curation/references/vault-conventions.md @@ -6,6 +6,7 @@ tags: - knowledge-management - obsidian - reference + - okf - ai area: Personal Knowledge Management project: @@ -13,45 +14,164 @@ project: # Vault Conventions -## Required Frontmatter +This vault follows the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) as its structural backbone. All notes, bundles, and links conform to OKF conventions unless noted below. -All notes should include YAML frontmatter with: +--- + +## Frontmatter Schema (merged — OKF + vault fields) + +Every non-reserved `.md` file **MUST** have YAML frontmatter with the following fields: ```yaml --- -id: unique-id -aliases: [] -tags: [] -area: Primary area/domain -project: [[Project Note]] +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required --- ``` -Use an empty value for `project:` when there is no relevant project note. +### Field Notes -## Core Principles +- **`type`** — Must be one of the OKF type names from the Type Vocabulary table below. This is the **only** required OKF field. +- **`title`** — Human-readable display name. If omitted, consumers may derive a title from the filename. +- **`description`** — One-line summary. Used by index.md generators, search snippets, and previews. +- **`resource`** — A URI identifying the underlying asset the concept describes. Omit for abstract ideas. +- **`tags`** — YAML list of short strings for cross-cutting categorization. Always include at least one tag. +- **`timestamp`** — ISO 8601 datetime of last meaningful change (e.g. `2026-07-06T12:00:00Z`). +- **`id`** — Stable unique identifier (kebab-case slug, never changes). +- **`aliases`** — List of alternative titles for search/discovery. +- **`area`** — Primary domain or area of knowledge. +- **`project`** — Associated project name, or empty string `''` when none. -- Markdown-first -- explicit `[[wikilinks]]` -- atomic notes for durable ideas -- project, topic, and date-based organization -- consistency over novelty +**OKF extensions:** Any additional producer-defined keys may be included. Consumers MUST preserve unknown keys when round-tripping. + +--- + +## Link Convention + +Use **standard markdown links**: `[text](relative/path.md)`. + +Do NOT use `[[wikilinks]]`. Obsidian renders standard markdown links identically to wikilinks, and markdown links are portable across all markdown renderers. + +### Link Forms + +| Target | Markdown form | +|--------|---------------| +| Another note in same directory | `[Note Title](Note%20Title.md)` | +| Note in subdirectory | `[Note Title](../Subdir/Note%20Title.md)` | +| Note with alias | `[alias](Note%20Title.md)` | +| Absolute (bundle-relative) | `[Note Title](/path/from/bundle/root.md)` | +| External URL | `[text](https://example.org)` | + +### When to Link + +Add links only when they express a real relationship: +- concept to broader concept +- source note to extracted idea +- project note to relevant knowledge note +- daily note to work done or ideas learned +- sibling concepts that genuinely inform one another + +Do not link on shared words alone. + +--- + +## Bundle Definition + +A **bundle** is a subdirectory that follows OKF progressive-disclosure conventions. Every bundle contains two reserved files: + +| File | Purpose | +|------|---------| +| `index.md` | OKF progressive-disclosure listing (no frontmatter, sections with bullet links) | +| `log.md` | OKF chronological update history (datestamped entries, newest first) | + +These filenames are **reserved** — they MUST NOT be used for concept documents. + +### Bundle root (vault root) + +`sjb-brain/` (the vault root) is a bundle. It has its own `index.md` and `log.md`. + +### Bundle map + +| Path | bundle? | +|------|:-------:| +| `sjb-brain/` (root) | ✅ | +| `Knowledge/` | ✅ | +| `Notes/` + subdirs | ✅ (each subdir is a sub-bundle) | +| `Resources/` + subdirs | ✅ (each subdir is a sub-bundle) | +| `Profiles/` | ✅ | +| `AI Conversation Summaries/` | ✅ | +| `Research//` | ✅ (each packet is a bundle) | +| `Projects//` | ✅ (each project is a bundle, migrate flat notes to dirs) | +| `Inbox/` | ❌ | +| `Dailies/` | ❌ | +| `Templates/` | ❌ | +| `Clippings/` | ❌ | +| `Tasks/`, `tools/`, `wts-services/` | ⏳ deferred | + +Non-bundle directories are treated as flat collections. They do not get `index.md` or `log.md`. + +--- + +## Type Vocabulary + +The following OKF type names are used in this vault. Every note MUST have exactly one `type` from this table. + +| type | Purpose | +|------|---------| +| `Inbox` | Raw capture, unprocessed | +| `Source` | Based on external material | +| `Concept` | One durable evergreen idea | +| `Project` | Active work, planning | +| `Daily` | Day-specific activity | +| `Reference` | Lookup material, specs | +| `Conversation Report` | Narrative summary of conversation | +| `Conversation Transcript` | Raw conversation transcript | +| `Research Synthesis` | Compiled answer for a research topic | +| `Research Claim Index` | Collection of evidence-backed claims | +| `Research Source List` | Index of sources consulted | +| `Research Glossary` | Term definitions for a topic | +| `Research Questions` | Open and resolved questions | +| `Research Log` | Chronological research session log | +| `MOC` | Map of content / curated index | +| `Template` | Template note for note creation | +| `Person` | A person you want notes about | +| `Tool` | A tool, app, or service | + +--- ## Folder Roles -- `Inbox/`: raw capture and unprocessed notes -- `Dailies/`: day-specific notes and reflection -- `Templates/`: note templates -- `Knowledge/`: preferred home for evergreen atomic notes if the folder exists or is created -- project/topic folders: active work and structured reference material +- `Inbox/`: raw capture and unprocessed notes (not a bundle) +- `Dailies/`: day-specific notes and reflection (not a bundle) +- `Templates/`: note templates (not a bundle) +- `Clippings/`: clipped web articles (not a bundle) +- `Knowledge/`: preferred home for evergreen atomic notes (bundle) +- `Notes/`: technical and domain notes, with subdirectories for each topic (bundle with sub-bundles) +- `Resources/`: reference and resource notes, with subdirectories for each domain (bundle with sub-bundles) +- `Profiles/`: notes about people (bundle) +- `AI Conversation Summaries/`: saved conversation summaries and transcripts (bundle) +- `Research//`: research packets, each a self-contained bundle +- `Projects//`: active project notes, each project a sub-bundle + +--- ## Task Conventions -- Use Markdown task items: `- [ ] Task description [[Project Name]]` +- Use Markdown task items: `- [ ] Task description [Project Name](Projects/Project%20Name.md)` - Add status and priority tags where useful - Use `due:: YYYY-MM-DD` for due dates - Add `start::` and `end::` only when explicitly requested or when tracking active work +--- + ## Curation Heuristics - A saved thing is not yet a knowledge note. @@ -59,3 +179,16 @@ Use an empty value for `project:` when there is no relevant project note. - A link should reflect a real conceptual or project relationship. - A long note may remain long if it is reference material; only extract notes when reuse is likely. - Prefer gradual improvement over mass refactoring. +- When creating or editing notes inside a bundle directory, maintain the bundle's `index.md` (add/update entries). +- When a bundle's contents change significantly, append an entry to the bundle's `log.md`. + +--- + +## Core Principles + +- Markdown-first +- OKF-conformant bundles with `index.md` and `log.md` +- Standard markdown `[...](...)` links (not wikilinks) +- Atomic notes for durable ideas +- Project, topic, and date-based organization +- Consistency over novelty -- 2.55.0 From de4f6f137b1ac31e5638a816ee75bb07cb23bb11 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Mon, 6 Jul 2026 21:34:55 -0400 Subject: [PATCH 2/2] phase4-7: rewrite PKM skills for OKF v0.1 alignment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 4: Rewrite research-vault skill - Packet becomes OKF bundle with index.md (no frontmatter) and log.md - All packet pages get proper type frontmatter - Atomic note template uses merged OKF + vault schema - Links use markdown [...](...) not wikilinks - Updated research-packet-template.md reference Phase 5: Rewrite pkm-curation skill - Frontmatter normalization adds type field using classification heuristics - Links use markdown [...](...) not wikilinks - Bundle awareness added (update index.md, log.md) - Updated agent-integration.md for OKF conventions Phase 6: Rewrite conversation-summary skill - AI Conversation Summaries/ bundle awareness (update index.md, log.md) - Report and transcript notes get merged frontmatter with proper type - Links use markdown [...](...) not wikilinks Phase 7: Review crit skill - No vault I/O changes needed — pure brainstorming framework --- common/pkm/conversation-summary/SKILL.md | 41 ++++- common/pkm/pkm-curation/SKILL.md | 134 +++++++++------ .../references/agent-integration.md | 21 ++- common/pkm/research-vault/SKILL.md | 107 ++++++++++-- .../references/research-packet-template.md | 156 ++++++++++++++---- 5 files changed, 354 insertions(+), 105 deletions(-) diff --git a/common/pkm/conversation-summary/SKILL.md b/common/pkm/conversation-summary/SKILL.md index 176c709..fa18007 100644 --- a/common/pkm/conversation-summary/SKILL.md +++ b/common/pkm/conversation-summary/SKILL.md @@ -1,10 +1,10 @@ --- name: conversation-summary -description: Save the current conversation as a comprehensive report note in your Obsidian vault. +description: Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions. disable-model-invocation: true --- -Save this conversation as two linked files in your Obsidian vault: a report (the narrative) and a transcript (the raw conversation). +Save this conversation as two linked files in your Obsidian vault: a report (the narrative) and a transcript (the raw conversation). The files live inside the `AI Conversation Summaries/` bundle and follow OKF v0.1 conventions. ## Report @@ -18,7 +18,32 @@ Write a thorough, standalone report as a Markdown note. A rich narrative in pros The report must be self-contained — someone reading it later should understand the full discussion, including the reasoning and all relevant details, without having been there. Err on the side of including too much detail rather than too little. -Include a link to the companion transcript where it fits naturally — an Obsidian wikilink like `[[{{title}}_transcript]]` in the section where it makes the most sense (often near the end). +Include a link to the companion transcript where it fits naturally — a markdown link like `[transcript](2026-05-23_16-35_obsidian-summary-skill-upgrade_A7K2_transcript.md)` in the section where it makes the most sense (often near the end). + +## Frontmatter + +Both the report and the transcript use the merged OKF + vault frontmatter schema: + +```yaml +--- +type: Conversation Report # report: Conversation Report, transcript: Conversation Transcript +title: +description: +tags: [conversation, ] +timestamp: +id: +aliases: [] +area: +project: '' +--- +``` + +## Bundle Awareness + +`AI Conversation Summaries/` is an OKF bundle. After writing each new report/transcript pair: + +1. Update `AI Conversation Summaries/index.md` — add an entry for the new report and transcript. +2. Append an entry to `AI Conversation Summaries/log.md` noting the addition. ## Transcript @@ -33,6 +58,14 @@ Save both files to `AI Conversation Summaries/` under your vault root. Create th - Report: `YYYY-MM-DD_HH-mm_.md` - Transcript: `YYYY-MM-DD_HH-mm__transcript.md` +## Links + +Use standard markdown links: `[text](relative/path.md)`. Do NOT use `[[wikilinks]]`. + +Link the report to its transcript and vice versa using filenames: +- In report: `[transcript](YYYY-MM-DD_HH-mm__transcript.md)` +- In transcript: `[report](YYYY-MM-DD_HH-mm_.md)` + ## Safety - Use only facts from the conversation. Do not invent references, decisions, or conclusions. @@ -40,4 +73,4 @@ Save both files to `AI Conversation Summaries/` under your vault root. Create th ## Done -Confirm both file paths and a one-sentence description of what the report covers. +Confirm both file paths and a one-sentence description of what the report covers. Also confirm that `AI Conversation Summaries/index.md` and `log.md` were updated. diff --git a/common/pkm/pkm-curation/SKILL.md b/common/pkm/pkm-curation/SKILL.md index 4d74d18..0f913f1 100644 --- a/common/pkm/pkm-curation/SKILL.md +++ b/common/pkm/pkm-curation/SKILL.md @@ -1,23 +1,24 @@ --- name: pkm-curation -description: Curate an Obsidian vault — classify notes, normalize frontmatter, add wikilinks, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. +description: Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. --- # PKM Curation -Use this skill when working inside a Markdown-first vault that values curation over collection. +Use this skill when working inside a Markdown-first vault that follows the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) conventions. ## Goals - Turn raw notes into reusable atomic notes. - Keep new notes consistent with vault conventions. -- Strengthen the link graph with meaningful `[[wikilinks]]`. +- Strengthen the link graph with meaningful markdown links. - Extract atomic notes from long or mixed-topic notes. +- Maintain bundle integrity: update index.md and log.md when adding or changing bundle contents. ## Read This First - Read `AGENTS.md` in the current repo scope before editing notes. -- Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders. +- Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders. This reference now documents the merged OKF + vault frontmatter schema. - Read `references/agent-integration.md` when running this skill through an agent. - Keep changes small and reviewable. - Keep file operations local to the vault unless the user explicitly asks otherwise. @@ -29,13 +30,13 @@ Use this skill when working inside a Markdown-first vault that values curation o fd --type f ".md" "path/to/obsidian-vault" | rg -i "keyword" # Search by content -rg -l "keyword" "path/to/obsidian-vault" --include "*.md" +rg -l "keyword" "path/to/obsidian-vault" -g "*.md" -# Find backlinks to a note -rg -l "\\[\\[Note Title\\]\\]" "path/to/obsidian-vault" --include "*.md" +# Find backlinks to a note (markdown link form) +rg -l "Note Title" "path/to/obsidian-vault" -g "*.md" -# Find index notes -fd --type f "Index" "path/to/obsidian-vault" +# Find bundle index files +fd "index.md" "path/to/obsidian-vault" ``` ## Rules @@ -46,60 +47,85 @@ fd --type f "Index" "path/to/obsidian-vault" - Preserve the user's voice unless the user asks for a rewrite. - Keep source material and evergreen ideas separate when possible. - Treat `Inbox/` as temporary capture, not long-term storage. -- Preserve all command blocks, code snippets, configuration directives, and - step-by-step instructions verbatim. Do not summarize or condense them. -- For reference/source notes: add a brief overview at the top, but keep the - original commands and details intact below. Completeness > brevity. +- Preserve all command blocks, code snippets, configuration directives, and step-by-step instructions verbatim. Do not summarize or condense them. +- For reference/source notes: add a brief overview at the top, but keep the original commands and details intact below. Completeness > brevity. - Read every file completely before moving, renaming, or modifying it. Do not rely on head/tail, heading-only scans, or partial reads to judge a file's content. +- **Bundle awareness**: When creating or editing notes inside a bundle directory, update the bundle's `index.md` (add or update the entry) and append an entry to `log.md`. ## Note-Type Heuristics -### Inbox note +Use the type vocabulary from `references/vault-conventions.md`. When inferring a type for a note, use these heuristics: +### Inbox note → `type: Inbox` Use when the note is raw capture, partial thinking, copied text, or an unprocessed link dump. +- Actions: clean obvious structure issues, add frontmatter if missing, classify for later promotion, avoid over-polishing unless requested. -Actions: -- clean obvious structure issues -- add frontmatter if missing -- classify for later promotion -- avoid over-polishing unless requested - -### Source note - +### Source note → `type: Source` Use when the note is based on an article, video, book, paper, transcript, or other external material. +- Actions: keep source context intact, summarize key takeaways, extract reusable ideas into separate atomic notes, link to related concepts and projects. -Actions: -- keep source context intact -- summarize key takeaways -- extract reusable ideas into separate atomic notes -- link to related concepts and projects - -### Atomic note - +### Atomic note → `type: Concept` Use when the note captures one durable idea, concept, claim, pattern, or insight. +- Actions: ensure one main idea per note, make the title concept-focused, add links to neighboring ideas, keep it concise and self-contained. -Actions: -- ensure one main idea per note -- make the title concept-focused -- add links to neighboring ideas -- keep it concise and self-contained - -### Project note - +### Project note → `type: Project` Use when the note supports active work, planning, resources, decisions, or tasks. +- Actions: preserve project context, link tasks to the project note, avoid turning active project logistics into evergreen notes unless there is a reusable insight. -Actions: -- preserve project context -- link tasks to the project note -- avoid turning active project logistics into evergreen notes unless there is a reusable insight - -### Daily note - +### Daily note → `type: Daily` Use when the note is date-based and captures activity, learning, tasks, or reflection for a single day. +- Actions: preserve chronology, link out to durable notes rather than stuffing ideas into the daily note. -Actions: -- preserve chronology -- link out to durable notes rather than stuffing ideas into the daily note +### Reference note → `type: Reference` +Use when the note is lookup material, documentation, specs, or external reference. +- Actions: preserve the reference content, add structured overview at top, link to related notes. + +## Frontmatter Normalization + +All notes should have the merged OKF + vault frontmatter schema: + +```yaml +--- +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required +--- +``` + +When normalizing existing frontmatter: +- Add `type` using the classification heuristics above. +- Ensure `id` is a stable kebab-case slug. +- Ensure `timestamp` is ISO 8601 format. +- Ensure `project` is a plain string, not a `[[wikilink]]`. +- Preserve any additional OKF extension keys. + +## Link Convention + +Use **standard markdown links**: `[text](relative/path.md)`. Do NOT use `[[wikilinks]]`. + +When converting existing wikilinks: +- `[[Note Title]]` → `[Note Title](Note%20Title.md)` +- `[[Note Title|alias]]` → `[alias](Note%20Title.md)` + +Use vault-relative paths from the linking file to the target. + +## Bundle Awareness + +When working inside a bundle directory: +- **After creating a new note**: add an entry to the bundle's `index.md` and append an entry to `log.md`. +- **After modifying an existing note**: if the change is significant, update the description in `index.md` and append an entry to `log.md`. +- **After deleting or moving a note**: remove or update its entry in `index.md` and append an entry to `log.md`. + +The bundle map is defined in `references/vault-conventions.md`. Key bundle directories include: `Knowledge/`, `Notes/` (with sub-bundles), `Resources/` (with sub-bundles), `Profiles/`, `AI Conversation Summaries/`, `Research//`, `Projects//`. + +Non-bundle directories (`Inbox/`, `Dailies/`, `Templates/`, `Clippings/`) do not get `index.md` or `log.md`. ## Linking Guidance @@ -122,21 +148,22 @@ Extract atomic notes when a note contains: - a reusable method, distinction, or definition - a concept that should be linked from many places -Keep extracted notes short. One note, one idea. +Keep extracted notes short. One note, one idea. When extracting into a bundle directory, update `index.md` and `log.md`. ## Common Tasks ### Curate one note 1. Inspect the target note and locate its file in the vault. -2. Identify the note type: inbox, source, atomic, project, daily, or reference. -3. Normalize frontmatter and basic structure. +2. Identify the note type: inbox, source, concept, project, daily, reference, or person. +3. Normalize frontmatter and basic structure using the merged schema. 4. Clarify the title if vague or timestamp-like. 5. Tighten headings and summary; distill if it mixes too many ideas. -6. Inspect nearby related notes, then add a few strong `[[wikilinks]]`. +6. Inspect nearby related notes, then add a few strong markdown links. 7. If the note contains multiple durable ideas, extract 1-3 atomic notes. 8. Suggest moving only if the destination is clearly better. -9. Patch the note in place and return a short summary of edits. +9. If inside a bundle, update `index.md` and `log.md`. +10. Patch the note in place and return a short summary of edits. **Completion Criterion**: Note inspected, classified, normalized, linked, and patched, with a summary returned to the user. @@ -187,6 +214,7 @@ When responding to the user: - name the file or files touched - separate completed edits from suggested next actions - call out anything that still needs user confirmation +- mention any bundle index/log updates made ## If You Need More Context diff --git a/common/pkm/pkm-curation/references/agent-integration.md b/common/pkm/pkm-curation/references/agent-integration.md index a75f378..0d8a78b 100644 --- a/common/pkm/pkm-curation/references/agent-integration.md +++ b/common/pkm/pkm-curation/references/agent-integration.md @@ -5,15 +5,16 @@ aliases: tags: - knowledge-management - reference + - okf area: Personal Knowledge Management -project: +project: '' --- # Agent Integration ## Purpose -This skill should be usable from any agent, and it should also fit chat environments where the agent as tool access. +This skill should be usable from any agent, and it should also fit chat environments where the agent has tool access. ## Recommended Role @@ -21,6 +22,14 @@ This skill should be usable from any agent, and it should also fit chat environm - interactive note refinement, serendipity review, and exploratory linking sessions - editor-side entry point that delegates vault actions to agent where possible +## Bundle Awareness + +The vault follows OKF v0.1 bundle conventions. When running curation tasks: + +- Creating a note inside a bundle directory: add an entry to `index.md` and an event to `log.md`. +- Modifying a note inside a bundle: update `index.md` description if the note's purpose changes; append to `log.md` for significant changes. +- Moving notes between bundle directories: update both source and destination bundle files. + ## Preferred Behaviors - search the vault before proposing links @@ -29,14 +38,16 @@ This skill should be usable from any agent, and it should also fit chat environm - summarize edits in plain Markdown - ask before removing any content or links from a note - ask before moving, renaming, or creating many files +- update bundle `index.md` and `log.md` when creating notes inside bundles ## Good Task Shapes -- curate a specific note -- process a small `Inbox/` batch +- curate a specific note (normalize frontmatter, classify type, add markdown links) +- process a small `Inbox/` batch (classify and normalize) - review recent notes for missing links - extract atomic notes from one source note - run a serendipity review against a current topic +- update or regenerate bundle `index.md` for a directory ## Avoid @@ -44,8 +55,10 @@ This skill should be usable from any agent, and it should also fit chat environm - broad speculative linking passes - converting every long note into atomic notes - changing note titles without stating why +- using `[[wikilinks]]` — always use standard markdown `[...](...)` links ## Portability Guidance - keep the workflow in `SKILL.md` tool-agnostic where possible - prefer small deterministic file edits so the skill remains portable to other `SKILL.md`-based agents +- always reference `vault-conventions.md` for the current frontmatter schema and type vocabulary diff --git a/common/pkm/research-vault/SKILL.md b/common/pkm/research-vault/SKILL.md index bee1bbb..bde226e 100644 --- a/common/pkm/research-vault/SKILL.md +++ b/common/pkm/research-vault/SKILL.md @@ -1,16 +1,95 @@ --- name: research-vault -description: Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked Obsidian research packet. +description: Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault. disable-model-invocation: true --- # Research Vault -Use when the user wants to learn or research a topic conversationally and save the outcome in an Obsidian vault. +Use when the user wants to learn or research a topic conversationally and save the outcome in an Obsidian vault using the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). ## Packet -Create one vault folder per research run, normally `Research/ /`, 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. +Create one vault folder per research run, normally `Research/ /`, containing an OKF bundle with `index.md` (progressive-disclosure listing, no frontmatter), `log.md` (chronological), and packet pages. Load `references/research-packet-template.md` before writing packet files or when exact structure matters. + +### Bundle structure + +``` +Research/ / +├── index.md # OKF progressive-disclosure, no frontmatter +├── log.md # OKF chronological, datestamped entries (newest first) +├── Sources.md # Research Source List +├── Synthesis.md # Research Synthesis +├── Claims.md # Research Claim Index +├── Questions.md # Research Questions +├── Conversation.md # Conversation Report +├── Glossaries.md # Research Glossary +└── .md # Concept / atomic notes +``` + +### Reserved filenames + +`index.md` and `log.md` are reserved — they MUST follow OKF format and MUST NOT be used for concept documents. + +### Frontmatter schema (merged — OKF + vault fields) + +Every concept document (non-reserved `.md` file) MUST have: + +```yaml +--- +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required +--- +``` + +Use the type vocabulary from `references/vault-conventions.md`. + +### `index.md` (OKF progressive-disclosure) + +No frontmatter. Sections with bullet links and descriptions: + +```markdown +# + +## Purpose +- Learning goal: +- Scope: +- Success criteria: + +## Packet Map +- [Sources](Sources.md) — compiled source list +- [Synthesis](Synthesis.md) — synthesized answer +- [Claims](Claims.md) — evidence-backed claims +- [Questions](Questions.md) — open and resolved questions +- [Conversation](Conversation.md) — raw conversation record +- [Glossaries](Glossaries.md) — term definitions +- [Log](Log.md) — session log + +## Compiled Pages +| Page | Type | Purpose | Status | +|---|---|---|---| +| | | | draft \| reviewed \| promoted | +``` + +### `log.md` (OKF chronological) + +Datestamped entries, newest first: + +```markdown +# Log + +## YYYY-MM-DD +* **Event type**: Description of what happened. +* **Files changed**: ... +``` ## Workflow @@ -18,12 +97,12 @@ Create one vault folder per research run, normally `Research/ /` unless the vault has a clearer convention. -## Required files +The packet is an OKF bundle. See [vault-conventions.md](../../pkm-curation/references/vault-conventions.md) for the full frontmatter schema and type vocabulary. -### `Index.md` +## Bundle structure + +``` +Research/ / +├── index.md # OKF progressive-disclosure, no frontmatter +├── log.md # OKF chronological, datestamped entries (newest first) +├── Sources.md # Research Source List +├── Synthesis.md # Research Synthesis +├── Claims.md # Research Claim Index +├── Questions.md # Research Questions +├── Conversation.md # Conversation Report +├── Glossaries.md # Research Glossary +└── .md # Concept +``` + +### `index.md` + +No frontmatter. Progressive-disclosure listing: ```markdown # @@ -18,19 +35,19 @@ Use inside `Research/ /` unless the vault has a clearer conve - ## Packet Map -- [[Sources]] -- [[Synthesis]] -- [[Claims]] -- [[Questions]] -- [[Conversation]] -- [[Glossaries]] -- [[Log]] +- [Sources](Sources.md) — compiled source list +- [Synthesis](Synthesis.md) — synthesized answer +- [Claims](Claims.md) — evidence-backed claims +- [Questions](Questions.md) — open and resolved questions +- [Conversation](Conversation.md) — raw conversation record +- [Glossaries](Glossaries.md) — term definitions +- [Log](Log.md) — session log ## Related Vault Notes - ## Compiled Pages -| Page | Type | One-line purpose | Source basis | Status | +| Page | Type | Purpose | Source basis | Status | |---|---|---|---|---| | | source summary \| concept \| claim cluster \| synthesis \| promoted | | | draft \| reviewed \| promoted | @@ -38,9 +55,33 @@ Use inside `Research/ /` unless the vault has a clearer conve - ``` +### `log.md` + +Datestamped entries, newest first. No frontmatter required (concept notes in the bundle DO need frontmatter, but log.md follows OKF §7 format). + +```markdown +# Log + +## YYYY-MM-DD +* **Event**: Description of what changed. +* **Files changed**: ... +``` + ### `Sources.md` ```markdown +--- +type: Research Source List +title: - Sources +description: Compiled source list for . +tags: [research, sources] +timestamp: +id: -sources +aliases: [] +area: Research +project: '' +--- + # Sources | Source | Type | Why useful | Reliability notes | Accessed | @@ -60,6 +101,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Synthesis.md` ```markdown +--- +type: Research Synthesis +title: - Synthesis +description: Compiled answer for research. +tags: [research, synthesis] +timestamp: +id: -synthesis +aliases: [] +area: Research +project: '' +--- + # Synthesis ## Short Answer @@ -79,6 +132,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Claims.md` ```markdown +--- +type: Research Claim Index +title: - Claims +description: Evidence-backed claims for research. +tags: [research, claims] +timestamp: +id: -claims +aliases: [] +area: Research +project: '' +--- + # Claims ## Claim: @@ -96,6 +161,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Questions.md` ```markdown +--- +type: Research Questions +title: - Questions +description: Open and resolved questions for research. +tags: [research, questions] +timestamp: +id: -questions +aliases: [] +area: Research +project: '' +--- + # Questions ## User Questions @@ -114,6 +191,18 @@ Include source links, books, papers, docs, videos, examples, search terms, or re ### `Conversation.md` ```markdown +--- +type: Conversation Report +title: - Conversation +description: Narrative summary of the research conversation for . +tags: [research, conversation] +timestamp: +id: -conversation +aliases: [] +area: Research +project: '' +--- + # Conversation ## Learning Goal @@ -132,25 +221,21 @@ 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 — -- Input: -- Files read: -- Files changed: -- Claims added or revised: -- Links added: -- Open issues: -``` - ### `Glossaries.md` ```markdown +--- +type: Research Glossary +title: - Glossary +description: Term definitions for research. +tags: [research, glossary] +timestamp: +id: -glossary +aliases: [] +area: Research +project: '' +--- + # Glossaries ## @@ -167,12 +252,17 @@ Add every acronym, abbreviation, domain-specific phrase, specialized term, jargo ```markdown --- +type: Concept +title: +description: . +tags: [research, atomic-note, ] +timestamp: id: aliases: [] -tags: [research, atomic-note] area: -project: [[]] +project: --- + # ## Idea @@ -182,7 +272,7 @@ project: [[]] ## Evidence or source -- Claim: [[Claims#Claim ]] +- Claim: [Claims](Claims.md) - Source: ## Links @@ -191,5 +281,9 @@ project: [[]] - Contrasts: ## Promotion status -- Packet-local | candidate for main vault | promoted to [[path/to/promoted note]] +- Packet-local | candidate for main vault | promoted to [path/to/promoted note](path/to/promoted.md) ``` + +## Linking + +Use standard markdown links `[text](relative/path.md)` throughout. Do NOT use `[[wikilinks]]`. Intra-packet links are bundle-relative (e.g., `[Claims](Claims.md)`). Cross-bundle links use vault-relative paths. -- 2.55.0