diff options
Diffstat (limited to '')
9 files changed, 1178 insertions, 0 deletions
diff --git a/.agents/skills/obsidian-project-memory/references/AGENT-FIRST-IMPORT.md b/.agents/skills/obsidian-project-memory/references/AGENT-FIRST-IMPORT.md new file mode 100644 index 0000000..9346bbd --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/AGENT-FIRST-IMPORT.md @@ -0,0 +1,52 @@ +# Agent-First Import + +## When to use this workflow + +Use agent-first import when: +- a repository already contains substantial project documents, +- the user says the knowledge base lacks background, +- multiple sources must be combined into a stable project summary, +- the project needs a real overview instead of a folder skeleton. + +## Recommended source-reading order + +Read only the most informative sources first: + +1. `README.md` if it is meaningful +2. `plan/` or `docs/` design notes +3. `outputs/analysis/` reports and summaries +4. `run/conf/` for task protocol and experimental assumptions +5. `src/analysis_module/` or other orchestration code for analysis modes +6. `TODO.md` or scratch notes only as supplemental context + +## What the agent should extract + +Ask the agent to produce these sections: +1. project background and research goal +2. core research questions +3. current main experiment lines +4. key results and conclusions +5. codebase-to-knowledge-base mapping +6. recommended durable notes to create or update +7. top content for `00-Hub.md` + +## After the agent returns + +Do not paste the entire agent response into the vault. + +Instead: +- convert the synthesis into durable notes, +- keep one idea per note, +- put high-level framing in `Knowledge/`, +- put experiment logic in `Experiments/`, +- put findings in `Results/`, +- put literature-facing material in `Papers/`. + +## Anti-pattern + +Do not treat file paths as meaning. + +Examples of bad behavior: +- mapping every `plan/*.md` file into a one-to-one note automatically, +- generating empty notes because a folder exists, +- creating new notes before understanding which sources matter. diff --git a/.agents/skills/obsidian-project-memory/references/KNOWLEDGE-CRUD.md b/.agents/skills/obsidian-project-memory/references/KNOWLEDGE-CRUD.md new file mode 100644 index 0000000..9f83e6f --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/KNOWLEDGE-CRUD.md @@ -0,0 +1,125 @@ +# Knowledge CRUD + +Use these rules when maintaining a research-project knowledge base. + +## Core defaults + +- **One canonical note per durable object** +- **Prefer updating over duplicating** +- **Raw material is not durable knowledge** +- **Archive by default; purge only on explicit request** +- **Query narrowly first, synthesize second** + + +## Default research progression + +When a research turn is substantive, prefer moving durable knowledge forward along this path: + +``` +Papers -> Experiments -> Results -> Writing +``` + +Interpretation: +- a paper note should often end with a testable takeaway, not only a summary, +- an experiment note should clarify what evidence would justify a result note, +- a result note should usually clarify what writing object should absorb the claim next. + +This progression does not mean every turn must touch all four folders. It means the next durable handoff should be made explicit whenever it is already clear. + +## Create + +When new knowledge appears, answer two questions first: + +1. Which type is it? + - `knowledge` + - `paper` + - `experiment` + - `result` + - `writing` + - `daily` +2. Is it a **durable note** or **raw material**? + +Default policy: **summarize first, then route**. + +Promote directly only when the content is already: +- self-contained, +- stable, +- clearly bounded, +- likely to be referenced later. + +Otherwise: +- merge it into the existing canonical note for the same object, or +- stage it in `Daily/` if it is not stable enough yet. + +Never: +- map new files one-to-one into new durable notes by path alone, +- create a new canonical note for the same experiment/result/paper without a real distinction, +- turn every discovered Markdown file into a formal vault object. + +## Read + +Use the smallest sufficient read set first. + +### Query presets + +- broad project question -> `00-Hub.md` + `Knowledge/Project-Overview.md` + `Knowledge/Research-Questions.md` +- next step / active work -> `01-Plan.md` + today's `Daily/` + project memory +- specific experiment -> matching note in `Experiments/` +- specific result -> matching note in `Results/` +- literature question -> matching note in `Papers/` + +### Query order + +1. canonical note +2. neighboring durable notes +3. daily or scratch context +4. repo source docs or outputs +5. agent synthesis + +Do not start by scanning the entire vault or repo when a canonical note already exists. + +## Update + +When new material overlaps an existing durable object: +- update the canonical note, +- do not create a sibling note by default. + +Update style by folder: +- `Knowledge/` -> rewrite stable conclusions; avoid timestamp noise +- `Experiments/` -> preserve experiment identity; add updates, findings, next steps +- `Results/` -> update headline, evidence, interpretation +- `Writing/` -> continue draft evolution or split by output object when necessary +- `Daily/` -> append freely; later promote durable parts + +Merge and split rules: +- merge several small notes when they are clearly about one durable object, +- split a note when it has grown into multiple durable objects with different lifecycles. + +## Delete + +Interpret deletion intent carefully: +- “remove / delete / stop using / no longer needed” -> archive +- “keep history but stop using” -> archive +- “permanently delete / purge” -> purge + +### Archive + +Default action: +- move the target note into `Archive/`, +- repair direct links in `00-Hub.md`, `01-Plan.md`, and explicit index notes, +- avoid leaving the main working surface with broken links. + +### Purge + +Only on explicit permanent-delete intent: +- delete the target note, +- clean direct links in `00-Hub.md`, `01-Plan.md`, and explicit index notes, +- ensure the deleted note was not the only canonical carrier of still-needed knowledge. + +### Rename or move + +Treat rename or move as: +- update of the same durable object, plus +- link repair + +Do not treat rename as delete-plus-create unless the object meaning actually changed. diff --git a/.agents/skills/obsidian-project-memory/references/NEW-MD-INGESTION.md b/.agents/skills/obsidian-project-memory/references/NEW-MD-INGESTION.md new file mode 100644 index 0000000..90c4070 --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/NEW-MD-INGESTION.md @@ -0,0 +1,81 @@ +# New Markdown Ingestion + +Use this guide when a new Markdown file appears and should be considered for the knowledge base. + +## Three-step decision + +### 1. Classify + +Classify the file as one of: +- `knowledge` +- `paper` +- `experiment` +- `result` +- `writing` +- `daily` + +### 2. Decide: durable note or raw material + +Treat it as a **durable note** only if it is already: +- complete enough to stand on its own, +- stable in scope, +- likely to be referenced later. + +Otherwise treat it as **raw material**. + +### 3. Choose the action + +Choose one of these: + +- **promote** + - use only when the file is already a stable, complete, long-lived note +- **merge** + - use when it supplements an existing canonical note for the same object +- **stage-to-daily** + - use when it is still unstable, incomplete, or not worth promoting yet + +Default answer: **summarize first, then route**. + +## Examples + +### New paper summary + +- likely classification: `paper` +- if complete and stable -> promote to `Papers/` +- if partial reading notes for an existing paper note -> merge + +### New experiment plan + +- likely classification: `experiment` +- if it defines a distinct experiment line -> promote to `Experiments/` +- if it refines an existing experiment -> merge into that note + +### New result memo + +- likely classification: `result` +- if it contains a durable conclusion with evidence -> promote to `Results/` +- if it is a full internal experiment summary report -> promote to `Results/Reports/` using the stable naming contract +- if it is still exploratory -> stage in `Daily/` or merge into the existing experiment note first + +### New meeting note + +- likely classification: `daily` +- default -> stage in `Daily/` +- promote only if the meeting produced a stable decision that belongs in `Knowledge/`, `Experiments/`, or `Writing/` + +### New scratch idea + +- likely classification: `daily` or `knowledge` +- default -> stage in `Daily/` +- promote later only if it becomes a stable research question, method direction, or experiment plan + + +### Cross-stage routing hint + +When a new file is about papers, experiments, results, or writing, do not stop at file classification alone. Also ask whether it clearly implies the next durable handoff: + +- paper note -> should an experiment note be updated? +- experiment note -> is there already a stable finding that belongs in `Results/`? +- result memo -> does a writing note need an update? + +If that next handoff is already clear, prefer updating the downstream canonical note in the same turn. diff --git a/.agents/skills/obsidian-project-memory/references/NOTE-ROUTING.md b/.agents/skills/obsidian-project-memory/references/NOTE-ROUTING.md new file mode 100644 index 0000000..f85bd5a --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/NOTE-ROUTING.md @@ -0,0 +1,140 @@ +# Note Routing + +## First decide: durable note or raw material + +### Durable note + +Treat content as a durable note when it is: +- likely to be referenced again after days or weeks, +- about a clearly bounded object, +- already stable enough to stand on its own, +- suitable to become the canonical note for that object. + +### Raw material + +Treat content as raw material when it is: +- a short-lived intermediate artifact, +- a draft, memo, scratch note, or meeting fragment, +- an unverified analysis dump, +- incomplete support for a note that already exists. + +Default rule: **raw material should be summarized before promotion**. + +## Route by knowledge type + +### Knowledge + +Write to `Knowledge/` when the content is stable and explanatory: +- project background +- research questions +- dataset protocol +- method landscape +- source inventory +- codebase overview + +Do not put these here by default: +- temporary ideas, +- unverified hypotheses with no stable framing, +- daily execution logs. + +### Papers + +Write to `Papers/` when the content is primarily literature-facing: +- single paper notes +- related-work summaries +- paper-to-project relevance notes +- reading notes and literature synthesis + +Do not put these here by default: +- project-only summaries with no literature object, +- raw meeting notes about papers, +- unrelated implementation notes. + +### Experiments + +Write to `Experiments/` when the content is about what was run or will be run: +- experiment design +- runbook +- ablation +- baseline comparison setup +- freezing / transfer / screening study + +Do not put these here by default: +- raw metric dumps with no interpretation, +- broad project framing, +- final cross-experiment claims that belong in `Results/`. + +### Results + +Write to `Results/` when the content captures a durable finding: +- final comparison +- mechanism conclusion +- collapse diagnosis +- figure and csv index +- cross-experiment interpretation +- stable canonical claim that should survive beyond one report + +Do not put these here by default: +- unprocessed analysis output, +- notes that merely restate the experiment setup, +- temporary result speculation that still belongs in `Daily/`. + +### Results Reports + +Write to `Results/Reports/` when the content is a **complete internal experiment summary report**: +- one experiment round retrospective, +- one batch report for a coherent experiment line, +- one decision-oriented wrap-up note backed by analysis artifacts. + +These notes should use the naming contract: +- `YYYY-MM-DD--{experiment-line}--r{round}--{purpose}.md` + +Do not put these here by default: +- manuscript-facing draft text, +- raw metric dumps, +- vague summaries without one date / line / round / purpose. + +### Writing + +Write to `Writing/` when the content is meant for external output: +- paper draft fragments +- slide narrative +- rebuttal notes +- proposal text + +Internal experiment reports do **not** belong here unless they are already external-facing writing artifacts. + +### Daily + +Write to `Daily/` when the content is transient or process-oriented: +- what happened today +- short sync queue +- quick scratch ideas +- temporary planning fragments +- lightweight meeting notes + +Do not let `Daily/` become the long-term home for canonical project knowledge. Promote durable content later. + +## Main routing rule + +If a note will still matter after several days or weeks, prefer `Knowledge/`, `Experiments/`, `Results/`, `Results/Reports/`, `Papers/`, or `Writing/`. + +If the note is mainly about today's progress or temporary organization, prefer `Daily/`. + +## Cross-folder promotion defaults + +Treat these folders as a research pipeline, not as independent buckets: + +- `Papers/` should usually answer: what should we test, compare, or borrow? +- `Experiments/` should usually answer: what exactly are we running, and what finding would matter? +- `Results/` should usually answer: what do we now believe, with evidence? +- `Results/Reports/` should usually answer: what happened in this round or batch, and what decision does it imply? +- `Writing/` should usually answer: what should be said externally because of those results? + +Default promotion path: +- paper insight -> experiment note +- stable experiment finding -> result note +- coherent round/batch retrospective -> results report note +- durable result claim -> writing note + +If a turn reaches only one stage, keep it there. But when the next stage is already clear, prefer updating the next canonical note instead of leaving the chain broken. diff --git a/.agents/skills/obsidian-project-memory/references/NOTE-TEMPLATES.md b/.agents/skills/obsidian-project-memory/references/NOTE-TEMPLATES.md new file mode 100644 index 0000000..b28c97f --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/NOTE-TEMPLATES.md @@ -0,0 +1,418 @@ +# Note Templates + +Templates should follow the project's configured `note_language`; if no note language is configured, default to English. + +The examples below are provided in both English and Chinese so agents can mirror the active note language while keeping a stable note shape. + +## Project Overview + +### English + +```markdown +# Project Overview + +## What this project studies +- ... + +## Why this problem is hard +- ... + +## Current project positioning +- ... + +## Most mature research direction so far +- ... +``` + +### 中文 + +```markdown +# 项目概览 + +## 这个项目研究什么 +- ... + +## 为什么这个问题难 +- ... + +## 当前项目定位 +- ... + +## 目前最成熟的研究分支 +- ... +``` + +## Research Questions + +### English + +```markdown +# Research Questions + +## Question 1 +- ... + +## Question 2 +- ... +``` + +### 中文 + +```markdown +# 研究问题 + +## 问题 1 +- ... + +## 问题 2 +- ... +``` + +## Experiment Note + +### English + +```markdown +# Experiment Name + +## Goal +- ... + +## Motivation from papers or prior results +- ... + +## Setup +- ... + +## Main steps +- ... + +## Updates +- ... + +## Findings +- ... + +## Promotion criteria for Results +- ... + +## Next steps +- ... +``` + +### 中文 + +```markdown +# 实验名称 + +## 目标 +- ... + +## 来自论文或已有结果的动机 +- ... + +## 设置 +- ... + +## 主要步骤 +- ... + +## 更新 +- ... + +## 发现 +- ... + +## 晋升到 Results 的条件 +- ... + +## 下一步 +- ... +``` + +## Result Note + +### English + +```markdown +# Result Name + +## Core conclusion +- ... + +## Evidence +- ... + +## Interpretation +- ... + +## Reusable writing points +- ... + +## Why it matters +- ... +``` + +### 中文 + +```markdown +# 结果名称 + +## 核心结论 +- ... + +## 证据 +- ... + +## 解读 +- ... + +## 可延续到写作中的内容 +- ... + +## 为什么重要 +- ... +``` + +## Results Report Note + +### English + +```markdown +--- +type: results-report +date: YYYY-MM-DD +experiment_line: example-line +round: 1 +purpose: transfer-summary +status: active +source_artifacts: + - analysis-output/analysis-report.md +linked_experiments: + - Experiments/Example.md +linked_results: + - Results/Example-Result.md +--- + +# Example Experiment Line / Round 1 / transfer-summary / YYYY-MM-DD + +## Executive summary +- ... + +## Experiment identity and decision context +- ... + +## Setup and evaluation protocol +- ... + +## Main findings +- ... + +## Statistical validation +- ... + +## Figure-by-figure interpretation +- ... + +## Failures / negative results / limitations +- ... + +## Which evidence changed the decision +- ... + +## Next actions +- ... + +## Artifact and reproduction index +- ... +``` + +### 中文 + +```markdown +--- +type: results-report +date: YYYY-MM-DD +experiment_line: example-line +round: 1 +purpose: transfer-summary +status: active +source_artifacts: + - analysis-output/analysis-report.md +linked_experiments: + - Experiments/Example.md +linked_results: + - Results/Example-Result.md +--- + +# 示例实验线 / 第 1 轮 / transfer-summary / YYYY-MM-DD + +## 执行摘要 +- ... + +## 实验身份与决策背景 +- ... + +## 设置与评测协议 +- ... + +## 主要发现 +- ... + +## 统计验证 +- ... + +## 图表逐项解读 +- ... + +## 失败案例 / 负结果 / 局限性 +- ... + +## 哪些证据改变了判断 +- ... + +## 下一步动作 +- ... + +## 产物与复现索引 +- ... +``` + +## Paper Note + +### English + +```markdown +# Paper Title + +## Citation +- ... + +## Core claims +- ... + +## Method +- ... + +## Evidence +- ... + +## Limitations +- ... + +## Direct relevance to this repository +- ... + +## Relation to other papers +- ... +``` + +### 中文 + +```markdown +# 论文标题 + +## 引文 +- ... + +## 核心主张 +- ... + +## 方法 +- ... + +## 证据 +- ... + +## 局限 +- ... + +## 与当前仓库的直接相关性 +- ... + +## 与其他论文的关系 +- ... +``` + +## Daily Note + +### English + +```markdown +# Daily Note - YYYY-MM-DD + +## Focus +- ... + +## Progress +- ... + +## Follow-up knowledge to promote +- ... + +## Next steps +- ... +``` + +### 中文 + +```markdown +# 日志 - YYYY-MM-DD + +## 关注重点 +- ... + +## 进展 +- ... + +## 后续可沉淀 +- ... + +## 下一步 +- ... +``` + + +## Writing Note + +### English + +```markdown +# Writing Item Name + +## Purpose +- ... + +## Supporting results +- ... + +## Paper background or comparisons +- ... + +## Draft argument +- ... + +## What is still missing before publication use +- ... +``` + +### 中文 + +```markdown +# 写作对象名称 + +## 目的 +- ... + +## 有哪些结果支撑 +- ... + +## 论文背景或对比 +- ... + +## 草拟论点 +- ... + +## 距离可发表使用还差什么 +- ... +``` diff --git a/.agents/skills/obsidian-project-memory/references/PAPERS-TO-WRITING.md b/.agents/skills/obsidian-project-memory/references/PAPERS-TO-WRITING.md new file mode 100644 index 0000000..e4b8237 --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/PAPERS-TO-WRITING.md @@ -0,0 +1,112 @@ +# Papers -> Experiments -> Results -> Writing + +Use this as the default durable research pipeline inside the project knowledge base. + +## Why this pipeline matters + +The vault should not treat literature, experiments, results, and writing as isolated folders. + +Default expectation: +1. `Papers/` produces hypotheses, reusable methods, baselines, and evaluation criteria. +2. `Experiments/` turns those into actionable test plans or updates an existing experiment line. +3. `Results/` captures the durable findings that survive beyond one run or one day. +4. `Writing/` turns those findings into external-facing synthesis: literature review, proposal text, draft claims, slides, rebuttal notes. + +`Daily/` is the staging area for temporary work and chronology, not the final destination for durable research objects. + +## Default handoff rules + +### Papers -> Experiments + +Promote from `Papers/` to `Experiments/` when a paper note yields: +- a testable hypothesis, +- a method variation worth implementing, +- a baseline worth reproducing, +- an ablation worth adding, +- an evaluation protocol or metric worth adopting. + +Default action: +- update the existing canonical experiment note if the idea belongs to an existing experiment line, +- otherwise create one new experiment note for the distinct experiment line, +- add a short back-link from the paper note to that experiment note. + +Do not stop at “this paper is relevant”; push at least to “what should we test because of it?” when the turn supports that level of specificity. + +### Experiments -> Results + +Promote from `Experiments/` to `Results/` when an experiment yields: +- a stable comparison, +- a repeatable failure pattern, +- a durable negative result, +- a mechanism insight, +- a decision-changing observation. + +Default action: +- keep transient run noise in `Daily/` or inside the experiment note, +- create or update a result note only when the observation is stable enough to cite later, +- link the result note back to the experiment note and vice versa. + +Do not create a result note for every run. Create one when the finding survives beyond raw logs. + +### Results -> Writing + +Promote from `Results/` to `Writing/` when a result yields: +- a claim that belongs in a paper, report, slide, or proposal, +- a useful comparison matrix, +- a project narrative update, +- a conclusion that should appear in a literature review or discussion section. + +Default action: +- update an existing writing note when the output object already exists, +- otherwise create one writing note per external object (review, proposal, draft section, slide outline, rebuttal block), +- keep links back to the result notes and key paper notes that support the claim. + +Do not let writing drift away from evidence. Every durable writing claim should link back to supporting results, and when useful, to the motivating papers. + +## Folder-by-folder default questions + +### For a paper note +Ask: +- What is the main reusable idea? +- Does it change what we should test? +- Which existing experiment line should absorb it? +- Does it belong in the active writing narrative yet? + +### For an experiment note +Ask: +- Which paper or prior result motivated this experiment? +- What decision would this experiment change? +- What evidence would justify promotion into `Results/`? +- What writing object would benefit if this experiment succeeds or fails? + +### For a result note +Ask: +- What is the durable claim? +- What evidence supports it? +- Which experiments and papers does it connect? +- Which writing artifact should absorb this claim next? + +### For a writing note +Ask: +- Which result notes support this text? +- Which paper notes provide context or comparison? +- Is this writing object current, or should it be updated from newer results? + +## Main anti-patterns + +Avoid these weak workflows: +- paper notes that never produce experiment decisions, +- experiment notes that never clarify what finding would count as durable, +- result notes that never feed any writing object, +- writing notes that drift away from linked evidence, +- keeping durable insights in `Daily/` instead of promoting them. + +## Default promotion heuristic + +When unsure, use this order: +1. update the existing paper note, +2. if it changes what should be tested, update or create the experiment note, +3. if it changes what is now believed, update or create the result note, +4. if it changes what should be said externally, update the writing note. + +This is the default durable research path unless the user clearly wants a narrower operation. diff --git a/.agents/skills/obsidian-project-memory/references/SCHEMA.md b/.agents/skills/obsidian-project-memory/references/SCHEMA.md new file mode 100644 index 0000000..a897ebf --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/SCHEMA.md @@ -0,0 +1,62 @@ +# Obsidian Project Knowledge Base Schema + +## Repository-local memory files + +- `.claude/project-memory/registry.yaml` — registry keyed by `project_id` +- `.claude/project-memory/<project_id>.md` — compact project memory snapshot used on project turns + +Note: `registry.yaml` is currently JSON-formatted on disk for historical compatibility. + +Optional per-project registry fields: +- `note_language` — note language for generated/synced notes. Supported values: `en`, `zh-CN`. + +Language resolution priority: +1. project config in `.claude/project-memory/registry.yaml` +2. environment variable `OBSIDIAN_NOTE_LANGUAGE` +3. default `en` + +## Vault layout + +```text +Research/{project-slug}/ + 00-Hub.md + 01-Plan.md + Knowledge/ + Papers/ + Experiments/ + Results/ + Reports/ + Writing/ + Daily/ + Archive/ +``` + +## Role of each top-level location + +- `00-Hub.md` — project homepage, current state, must-remember numbers, key links +- `01-Plan.md` — active goals, tasks, open questions, next actions +- `Knowledge/` — stable project understanding such as background, research questions, method survey, data protocol, source inventory +- `Papers/` — paper notes, literature summaries, related-work assets +- `Experiments/` — experiment designs, runbooks, ablations, mechanism studies +- `Results/` — canonical durable findings, diagnostics, figure/table indexes, cross-experiment conclusions +- `Results/Reports/` — internal experiment round reports and batch retrospectives with stable naming +- `Writing/` — paper drafting, slides, proposal text, rebuttal material +- `Daily/` — daily logs, lightweight sync queue, scratch notes, meeting fragments +- `Archive/` — inactive or historical material that should not stay in the main working surface + +## Minimum note types + +- `project` +- `daily` +- `paper` +- `experiment` +- `result` +- `results-report` +- `synthesis` +- `meta` +- `writing` +- `task` + +## Main design rule + +This schema is intentionally small. Prefer a few durable notes over many placeholder notes. diff --git a/.agents/skills/obsidian-project-memory/references/SCRIPT-VS-AGENT.md b/.agents/skills/obsidian-project-memory/references/SCRIPT-VS-AGENT.md new file mode 100644 index 0000000..b066064 --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/SCRIPT-VS-AGENT.md @@ -0,0 +1,49 @@ +# Script vs Agent Boundary + +Use this guide to decide whether a task belongs in `project_kb.py` or must remain agent-driven. + +## Good fit for the script + +These tasks are low-freedom, deterministic, and should behave the same every time: + +- detect whether a repo is bound to a project vault +- bootstrap the standard vault structure +- sync repo-driven state into daily, hub, plan, memory, and auto-sync notes +- list or suggest the canonical notes to read for a question shape +- archive, purge, or rename a single note with direct-link repair in explicit index notes +- maintain source inventory and codebase overview + +Current script-facing commands: +- `detect` +- `bootstrap` +- `sync` +- `lifecycle` +- `query-context` +- `find-canonical-note` +- `note-lifecycle` + +## Must stay with the agent + +These tasks require semantic judgment and should not be hard-coded into the script: + +- deciding whether a new Markdown file is durable knowledge or raw material +- deciding whether to promote, merge, or stage a new Markdown file +- deciding which existing note is the canonical note when multiple semantic candidates exist +- synthesizing background from many project documents +- interpreting experimental meaning or result significance +- deciding whether a note should be split or merged based on conceptual overlap +- deciding whether a result is stable enough for `Results/` + +## Practical rule + +If the task can be framed as: + +- “find”, “move”, “rename”, “archive”, “sync”, or “suggest reads” + +it is probably script-suitable. + +If the task can be framed as: + +- “understand”, “interpret”, “decide meaning”, “summarize”, “merge concepts”, or “promote to durable knowledge” + +it should remain agent-driven. diff --git a/.agents/skills/obsidian-project-memory/references/WORKFLOW.md b/.agents/skills/obsidian-project-memory/references/WORKFLOW.md new file mode 100644 index 0000000..6e57ee3 --- /dev/null +++ b/.agents/skills/obsidian-project-memory/references/WORKFLOW.md @@ -0,0 +1,139 @@ +# Workflow + +## 1. Detect + +Run: + +```bash +python3 scripts/project_kb.py detect --cwd "$PWD" +``` + +Use this to decide whether the repo: +- is already bound, +- should be bootstrapped, +- or should be left alone. + +## 2. Bootstrap + +Bootstrap only when the repository is a strong research-project candidate and no binding exists yet. + +```bash +python3 scripts/project_kb.py bootstrap --cwd "$PWD" --vault-path "$OBSIDIAN_VAULT_PATH" +``` + +Bootstrap should create only the compact schema from `SCHEMA.md`, including `Results/Reports/` for internal experiment reports. + +To bootstrap Chinese notes explicitly: + +```bash +python3 scripts/project_kb.py bootstrap --cwd "$PWD" --vault-path "$OBSIDIAN_VAULT_PATH" --note-language zh-CN +``` + +Language priority for generated/synced notes: +1. per-project `note_language` in `.claude/project-memory/registry.yaml` +2. environment variable `OBSIDIAN_NOTE_LANGUAGE` +3. default `en` + +Section updates remain compatible with both English and Chinese headings so older notes can still sync safely after switching the configured language. + +## 3. Daily or repo-driven sync + +Use: + +```bash +python3 scripts/project_kb.py sync --cwd "$PWD" --scope auto +``` + +Use sync for deterministic state maintenance only: +- refresh `00-Hub.md` +- refresh `01-Plan.md` +- refresh project memory +- write daily sync information +- keep source inventory and codebase overview fresh + +Do not rely on sync to derive project meaning from raw files. + +For read-side assistance or single-note lifecycle operations, use: + +```bash +python3 scripts/project_kb.py query-context --cwd "$PWD" --kind broad +python3 scripts/project_kb.py query-context --cwd "$PWD" --kind result --query "syllable-channel" +python3 scripts/project_kb.py find-canonical-note --cwd "$PWD" --kind experiment --query "freezing S7 speaking" +python3 scripts/project_kb.py note-lifecycle --cwd "$PWD" --mode archive --note "Results/Old-Result.md" +``` + +## 4. Agent-first import or synthesis + +When the vault lacks background or context, do not extend the script first. + +Instead: +1. ask an agent to read the most informative project sources, +2. synthesize project-level knowledge, +3. write durable notes back into `Knowledge/`, `Experiments/`, `Results/`, `Results/Reports/`, or `Papers/`. + +## 5. Advance along the main research path + +For substantive research turns, prefer advancing knowledge along this path: + +```text +Papers -> Experiments -> Results -> Writing +``` + +Typical progression: +- new paper understanding -> update `Papers/` and decide whether an experiment note should absorb a new hypothesis, baseline, or evaluation rule +- experiment planning or execution -> update `Experiments/` and decide what evidence would justify a result note +- stable finding -> update `Results/` and decide whether a round or batch retrospective should be written under `Results/Reports/` +- draft or review work -> update `Writing/` and keep links back to supporting results and papers + +Do not treat these folders as isolated silos. The default durable workflow is to move knowledge forward across them when the turn supports it. + +## 6. Incremental update rule + +For most turns, write the minimum durable delta only. + +Examples: +- small engineering change -> `Daily/` plus project memory +- new experiment design -> `Experiments/` +- new result interpretation -> `Results/` +- new internal experiment retrospective -> `Results/Reports/` +- new project framing -> `Knowledge/` +- new paper note -> `Papers/` + +## 7. Ingest a new Markdown file + +When a new `.md` file appears, do not route it by path alone. + +Use this sequence: +1. classify it as `knowledge`, `paper`, `experiment`, `result`, `writing`, or `daily`, +2. decide whether it is a **durable note** or **raw material**, +3. choose one of: + - **promote** into the matching top-level folder, + - **merge** into an existing canonical note, + - **stage to Daily** when it is still unstable. + +Examples: +- new `plan/new_idea.md` -> usually summarize first, then update `01-Plan.md` or `Knowledge/Research-Questions.md` +- a complete experiment summary -> usually promote to `Results/Reports/`, and update `Results/` if a stable conclusion is now supported +- a scratch meeting memo -> usually stage in `Daily/` + +`project_kb.py` may manage state around this process, but it does not decide promote vs merge. + +## 8. Update / archive / purge durable notes + +For durable notes: +- update the canonical note when the object already exists, +- create a new note only when the object is genuinely distinct, +- archive by default when the user wants to remove something, +- purge only on explicit permanent-delete intent. + +When archiving or purging, repair direct links in `00-Hub.md`, `01-Plan.md`, and explicit index notes. + +## 9. Lifecycle actions + +Default removal behavior is archive: + +```bash +python3 scripts/project_kb.py lifecycle --cwd "$PWD" --mode archive +``` + +Only purge when the user explicitly asks for permanent deletion. |