---
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.
