84 lines
4.8 KiB
Markdown
84 lines
4.8 KiB
Markdown
---
|
|
description: Write evergreen cross-project knowledge to the SecondBrain vault with correct frontmatter and scope. Use unprompted WHEN a durable fact surfaces mid-task — tool/API behavior discovered, a client convention, a methodology that worked — anything that would change how you act in a DIFFERENT repo. The vault, NOT auto-memory, is the destination for knowledge that generalizes beyond this repo; auto-memory is only for facts about this repo itself.
|
|
---
|
|
|
|
Use this skill when you have knowledge that should persist across projects and sessions.
|
|
|
|
## Where knowledge goes — ask in order
|
|
|
|
1. Does the repo already record it (code, ADR, CLAUDE.md, git history)? → write it there or
|
|
nowhere; never duplicate into memory.
|
|
2. Would this change how you act in a **different** repo, next year? → the **SecondBrain
|
|
vault** via this skill — NOT auto-memory. Facts about the world: tool behavior, client
|
|
conventions, API quirks, methodology that worked. The repo is where you *learned* it, not
|
|
what it's *about*.
|
|
3. Only useful in future sessions of **this** repo (where things live here, what we tried
|
|
here)? → auto-memory.
|
|
4. Task status, session state, in-flight progress → nothing (the session journal is handled
|
|
automatically by the SessionEnd hook).
|
|
|
|
Tiebreaker: what is the fact **about**? About a tool/client/API → vault. About this repo →
|
|
auto-memory. When a durable fact surfaces mid-task — even with no one saying "remember" —
|
|
run the ladder before moving on.
|
|
|
|
## Vault location — resolve it FIRST, mechanically
|
|
|
|
Before writing anything, resolve the vault root with one command and use ONLY the path it
|
|
prints for every read and write in this skill:
|
|
|
|
```bash
|
|
echo "${OS_VAULT_PATH:-$HOME/Documents/SecondBrain}"
|
|
```
|
|
|
|
Do not assume `~/Documents/SecondBrain` — `OS_VAULT_PATH` overrides it (tests and evals point
|
|
it at an isolated vault, and writing to the default path there contaminates the user's real
|
|
vault). Never write a vault note to a hardcoded path.
|
|
|
|
## 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.
|
|
- Frontmatter must be parseable YAML: quote any scalar value that contains a colon
|
|
(`title: "Chartkit segfaults without streaming: true"` — unquoted, that line breaks the
|
|
whole frontmatter block and the note drops out of retrieval).
|
|
|
|
**Write `summary` now.** Deferring it breaks retrieval.
|
|
|
|
## Update before create
|
|
|
|
Write is query-first: before creating a note, check for existing notes on the same subject
|
|
(grep the vault or use `/os-vault:query`). If the new fact contradicts, extends, or refines
|
|
an existing note → update that note and bump `last_updated`. Only a genuinely new subject
|
|
gets a new note.
|
|
|
|
## Content that fits no existing type
|
|
|
|
Do NOT invent a note type, and do not force a bad fit silently. Write the note under the
|
|
closest existing type with a visible `## Type-fit note` line saying what didn't fit — or, if
|
|
the shape is clearly recurring, propose a new type via `/os-vault:design-template`. Misfits
|
|
get reviewed in `/os-vault:reorganize`; three misfits of the same shape justify a new type.
|
|
|
|
## 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.
|