Skip to content

docs: define why-first vault profile (How/What/Why contract) #172

@maehwasoo

Description

@maehwasoo

Doc location

  • docs/standards/vault/assistant-workflow.md
  • docs/standards/vault/frontmatter-schema.md (usage guidance only; no enum changes)
  • docs/standards/vault/typed-links.md
  • docs/standards/vault/vault-structure.md

What’s wrong / missing?

  • We want to use the Obsidian vault as a shared-memory Why layer (rationale, decisions, mental models) while keeping the repository as the What source of truth (SoT: canonical reference).
  • The current vault docs define schema and ontology, but they do not clearly define a Why-first usage profile and retrieval priorities.
  • Without that contract, vault curation feels high-overhead and the graph becomes noisy or stale.
  • The docs also do not give a compact rule set for linking, archiving, and selecting the right layer for Why-oriented notes.

Suggested fix (optional)

  • Add a “Why-first vault profile” that defines the contract: How (Codex CLI) / What (repo SoT) / Why (vault).
  • Document the default retrieval policy: prefer layer: strategic|conceptual|logical and status: active|in-review; treat operational and archived as cold storage unless explicitly requested.
  • Document graph hygiene guidance: keep a navigable spine via part_of (>= 1), plus a small typed-link web (1–3 non-part_of links per note).
  • Add a 1-page cheat sheet for choosing layer for Why notes.
  • Add an explicit default do/don’t list for linking and archiving.
  • Non-goal: no tool or code changes in this issue; those should be tracked separately.

Metadata

Metadata

Assignees

Labels

docsImprovements or additions to documentation

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions