49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
---
|
|
description: Write evergreen knowledge to the SecondBrain vault with correct frontmatter and scope
|
|
---
|
|
|
|
Use this skill when you have knowledge that should persist across projects and sessions.
|
|
|
|
## Evergreen vs. ephemeral test
|
|
|
|
**Write to vault if:** the knowledge is reusable across projects (tool/API behavior, client-specific facts, conventions, cross-project patterns). Vault is for knowledge that survives the current session.
|
|
|
|
**Do NOT write to vault:** project-ephemeral state (current task, in-progress decisions, temporary context). These belong in project files or the episodic layer (session journal — handled automatically by SessionEnd hook).
|
|
|
|
## Vault location
|
|
|
|
The vault root is `~/Documents/SecondBrain` — unless the environment variable `OS_VAULT_PATH`
|
|
is set, in which case use that path as the vault root instead (rare; tests and evals use it to
|
|
point at an isolated vault).
|
|
|
|
## Frontmatter contract — read vault-conventions.md first
|
|
|
|
**Before writing any note, read `vault-conventions.md` at the vault root.** It is the
|
|
single source of truth for the frontmatter schema, note types, and tag taxonomy — do not rely
|
|
on a remembered or summarized version, and do not duplicate its schema here. This file will go
|
|
stale if the contract is ever reconciled again and this summary isn't updated with it.
|
|
|
|
Brief summary, correct as of the last time this skill was edited (verify against
|
|
vault-conventions.md, not this list, if anything looks off):
|
|
|
|
- `scope` is a frontmatter **field** (`global`/`project`/`client`), not a tag.
|
|
- `type` is both a frontmatter field and a `type/<...>` tag (kept in sync); valid values are
|
|
listed in vault-conventions.md's Note Types table (e.g. `howto`, `reference`, `convention`,
|
|
`eval-results`, `hub`, `adr`, `log` — the table is authoritative, this list is illustrative).
|
|
- Tags are flat and namespaced across six facets — `type/`, `client/`, `project/`, `domain/`,
|
|
`tool/`, `convention/`. `type/` is required; at least one other facet tag is recommended so the
|
|
note routes to the right context.
|
|
- Filenames are slug-only lowercase-kebab-case (no date prefix).
|
|
- Write `summary` at creation time — it is the primary router hint for graph traversal and
|
|
memsearch. Never defer it.
|
|
|
|
**Write `summary` now.** Deferring it breaks retrieval.
|
|
|
|
## Vault-not-repo rule
|
|
|
|
Write ONLY to the vault root (see Vault location above). Never silently write to a project repository what belongs in the vault. If in doubt, write to the vault.
|
|
|
|
## PostToolUse hook is automatic
|
|
|
|
When you write or edit a `.md` file in the vault, the PostToolUse hook records the vault write and invalidates the rebuild stamp — the graph refreshes incrementally (via `graphify extract --update`) at the next session start, not immediately. You do not need to run graphify manually.
|