cobsidian

name	cobsidian
description	Use when a user asks to organize, save, compare, review, map, or dissect conversations and source material into an Obsidian vault or Markdown knowledge base, including Chinese requests about 知识库, 笔记, 双链, 学习模式, 项目模式, 复盘模式, 对比模式, 索引模式, 捕获模式, or 拆解模式.

Cobsidian

Core Principle

Maintain the vault as a linked knowledge system. Do not just generate a standalone Markdown file.

Iron Law

NEVER WRITE TO THE VAULT WITHOUT SEARCHING EXISTING NOTES FIRST.

Dry-run is the default safe path. Skip it only when the user explicitly says to write immediately; the scan and duplicate checks still apply.

Response Language

Match the user's language for mode selection, clarification questions, Knowledge Read, and completion reports.

• Chinese request -> Chinese mode names and 整理判读.
• English request -> English mode names and Knowledge Read.
• Mixed-language request -> use the dominant user language and include canonical IDs when useful.

Vault Resolution

Resolve the target vault in this order:

1. Explicit vault path in the user's request.
2. cobsidian.config.yml with vault.path.
3. MCP host configuration through COBSIDIAN_CONFIG.
4. MCP host configuration through COBSIDIAN_VAULT.

Do not guess a private vault path. If no valid vault path is available, ask for one concise input: the vault path or the config path. If a supplied path is invalid, report it and request a corrected vault or config path before writing.

Mode Routing

Canonical mode	Representative cues	Use for	Load
learning / 学习	teach me about / 这个概念讲一下	Concepts and explanations	learning
project / 项目	document this repo / 这个仓库帮我分析一下	Project implementation and operations	project
review / 复盘	what went wrong / 失败复盘	Evidence, causes, and corrective actions	review
comparison / 对比	which should I choose / 哪个更好	Requirements-based decisions	comparison
index / 索引	learning path / 学习路线	Maps, paths, and hub notes	index
capture / 捕获	just save this / 先记下来	Low-friction temporary capture	capture
dissection / 拆解	how does X work internally / 拆解这个产品为什么有效 / 这个怎么实现的	Problem-to-outcome causal analysis, internal mechanics, horizontal peers, vertical evolution, and reusable advantages	dissection

• Explicit mode -> load only its mode reference.
• Clear inferred mode -> state it and load only its mode reference.
• Ambiguous mode -> recommend at most two modes with contextual reasons, then ask one concise question; do not dump all seven.
• Do not combine mode references unless the user explicitly requests separate outputs with separate mode decisions.

Host Routing

Detect the host's actual tools before loading only the matching host reference. Product names select invocation mappings, never capability levels.

• Codex
• Claude Code
• Kimi Code
• OpenCode
• Pi
• Antigravity
• GitHub Copilot CLI
• Cursor
• Hermes
• Generic MCP host

Map observed scan/write transport to full-local, filesystem-only, mcp-readonly, or chat-only. The historical mcp-readonly name means the transport-neutral effective read-only level, including local read-only operation without MCP. Report validation capability independently through validation_available; a write-capable host with no validation keeps its full-local or filesystem-only level and becomes not ready. Use preflight for readiness and degradation. Never load multiple host references speculatively.

Knowledge Read

Knowledge Read (整理判读) is always computed and remains in structured dry-run output. auto, always, and off change conversational presentation only:

• auto: compact for simple explicit work; expanded for inferred, deep, multi-note, or source-grounded work.
• always: expanded.
• off: hidden in conversation while the complete object remains in JSON.

Mode defaults apply before duplicate resolution. A requested granularity=append is valid only when decision.action=append; an actual append decision always forces append granularity. Evidence starts at conversation. Evidence upgrades require host-completed facts: source-grounded requires source_read_completed=true, while verified requires both source_read_completed=true and verification_completed=true. Mode choice and user claims never set these facts automatically.

Common Workflow

1. Detect host tools, map the scan/write capability level, report validation capability independently, and load one host reference.
2. Resolve the vault and target topic.
3. Scan existing notes, build note identities from filename, cleaned H1, frontmatter title and aliases, and prefix-free core titles, then complete duplicate and backlink checks across all identity candidates.
4. Select or infer one mode and load one mode reference.
5. Compute Knowledge Read and the mode-level note plan: single-note | multi-note | report-only; split means multi-note.
6. Produce dry-run output with decision.action: create | append | blocked, then evaluate preflight.
7. For local writes, prepare a deterministic patch preview with write_executor.py prepare, show the plan ID and diff, and require explicit confirmation of that exact plan ID.
8. Apply the confirmed plan atomically with write_executor.py apply; validate the result, retain the transaction record, and auto-roll back when the write introduces new validation warnings.
9. Report only completed actions. Use write_executor.py rollback with the exact transaction ID when the user requests a safe rollback.

Write Rules

• Preserve the vault's existing naming and organization style.
• Use vault-relative paths in note content; never embed user-specific absolute paths.
• Prefer append or merge over creating a near-duplicate.
• Prefer durable concepts over chat transcript summaries.
• Local operational records still use minimum necessary disclosure; redact credentials, tokens, private identifiers, and unnecessary raw log content.
• Add [[wiki links]] only to notes confirmed to exist; report missing targets instead of creating broken links.
• Treat filename, cleaned H1, frontmatter title and aliases, and prefix-free core titles as one note identity when checking duplicates.
• Do not bypass the deterministic executor with a direct edit when its local Python path is available. A preview is not approval, and a plan ID is valid only while the target hash is unchanged.
• Do not fabricate sources, filenames, scans, writes, or validation results.
• Use stable headings and keep each note responsible for one maintainable knowledge boundary.

Red Flags

Stop and reconsider when any of these thoughts appear:

• "This topic is obviously new, so scanning is unnecessary." Scan anyway.
• "The user said write, so dry-run is implicitly waived." Only an explicit opt-out waives dry-run.
• "The mode is unclear, so list every mode." Recommend no more than two contextual options.
• "This product usually has filesystem access." Detect actual tools and permissions first.
• "off means Knowledge Read need not be computed." It hides presentation only.
• "The host cannot perform the action, but the report can describe it as done." Report the blocked reason and degradation path instead.
• "Write exists, so missing validation means mcp-readonly." Keep the write transport level, set validation_available=false, and block readiness.

Helper Scripts

• scripts/scan_vault.py: summarize notes, titles, tags, and wiki links.
• scripts/note_identity.py: derive filename, H1, frontmatter, alias, and prefix-free identity candidates.
• scripts/find_duplicates.py: detect duplicate or similar note titles.
• scripts/suggest_backlinks.py: suggest related existing notes.
• scripts/validate_notes.py: report missing wiki links and hygiene issues.
• scripts/dry_run.py: return the zero-write plan, Knowledge Read, and preflight.
• scripts/write_executor.py: preview, confirm, atomically apply, validate, and roll back local writes.
• scripts/quality_eval.py: measure duplicate precision/recall, backlink precision@k, target accuracy, and mode accuracy on labeled JSONL cases.
• scripts/knowledge_read.py: validate mode defaults, evidence, granularity, and display policy.
• scripts/preflight.py: derive readiness and deterministic blocked reasons.

Use --config cobsidian.config.yml when project configuration supplies vault, threshold, backlink, validation, or interaction settings.

Read note types for shared note-shape guidance, backlink policy for links, and Markdown style for formatting.

Completion Report

End with:

• files created or modified, or an explicit no-write result
• dry-run decision.action: create | append | blocked
• mode-level note plan: single-note | multi-note | report-only; report split as multi-note, not a machine action
• selected mode, depth, granularity, and evidence level
• capability level, preflight readiness, and every blocked reason
• duplicate checks and backlink decisions
• validation result, or the exact reason validation was unavailable
• write plan ID and transaction status for local writes, including whether validation triggered an automatic rollback