---
summary: Universal conventions for all notes in this vault — naming, frontmatter, tag taxonomy, hub notes, and Graphify awareness.
tags:
  - type/meta
source: SecondBrain
date: 2026-06-08
---

# Vault Conventions

Universal conventions for all notes in this vault. One-stop reference for naming, frontmatter,
note types, hub notes, and tag vocabulary. Project-specific rules live in `project-config-*` notes.

This vault stores **durable, evergreen knowledge** — finished plans, decisions, research, how-tos,
and project learnings. It is NOT working memory. Working notes that don't yet have a permanent home
should not be archived here until they have something stable to say.

## Navigation

| I want to... | Do this |
|---|---|
| Know the note types | See Note Types below |
| Look up valid tag facets | See Tag Taxonomy below |
| Know file naming rules | See File Naming below |
| Understand hub notes | See Hub Notes below |
| Find project-specific context | Read the relevant `project-config-*` note |

## File Naming

`descriptive-slug.md`

- Slug is lowercase kebab-case
- No date prefix
- Directories by type: `convention/`, `reference/`, `howto/`

## Frontmatter Contract

Every note requires these fields. No exceptions; defer writing the `summary` for nothing. See [Standard Frontmatter Schema](#standard-frontmatter-schema) below for the authoritative schema.

**`summary` field rules:**
- One sentence, written by the human (or agent) at creation time.
- Describes what the note *is about*, not what it contains.
- Used by Graphify when building the knowledge graph and by the memory plugin for SessionStart injection.
- Never defer it. A placeholder summary defeats the purpose.

## Note Types (`type/` facet)

Use exactly one `type/` tag per note.

| Type tag | Use for |
|---|---|
| `type/reference` | Reference material: market research, competitive intel, research dumps |
| `type/plan` | Implementation plans, strategy docs |
| `type/log` | Session logs, increment logs, decisions |
| `type/adr` | Architecture decision records |
| `type/howto` | Process docs, step-by-step guides |
| `type/hub` | Hub notes: index/navigation notes linking 3+ related notes (see Hub Notes) |
| `type/eval-results` | Evaluation results: measurement data, confidence assessment, interpretation, deployment gates for skill/feature behavior testing |
| `type/clip` | Web clips, saved articles |
| `type/project-config` | Per-project tag inference rules and conventions |
| `type/meta` | Vault governance (this file, CLAUDE.md) |

## Tag Taxonomy

Tags are **flat and parallel** — no nested paths, no hierarchy inside a facet. Six facets (`scope` is a frontmatter field, not a tag):

| Facet | Purpose | Example |
|---|---|---|
| `type/` | Note type (see table above) | `type/howto` |
| `client/` | Client or company this pertains to | `client/acme` |
| `project/` | Specific project or engagement | `project/website-redesign` |
| `domain/` | Topic area or discipline | `domain/seo`, `domain/cold-email` |
| `tool/` | Tool, library, or platform referenced | `tool/graphify`, `tool/semrush` |
| `convention/` | Cross-project convention or pattern | `convention/api-style` |

**Rules:**
- Always include `type/`. All other facets are optional.
- Use multiple tags within a facet when accurate (e.g., `domain/seo` and `domain/cold-email`).
- Facets are not nested: `domain/cold-email` is correct; `domain/outbound/cold-email` is not.

## Hub Notes

When a topic has **3 or more related notes**, create a hub note (`type/hub`) that wikilinks to all
of them. Hub notes are the primary navigation mechanism — hierarchy and relationships live here,
not in nested folders or tag nesting.

A hub note should:
- Have a descriptive `summary` explaining what this cluster is about
- List wikilinks to all related notes with a one-line description of each
- Use `type/hub` as the type tag
- Be linked back to from the notes it indexes (add a `## Related` section)

Hierarchy lives in hub notes + wikilinks, not in folder structure or tag nesting.

## Graphify Awareness

The `graphify-out/` directory at the vault root is **generated by Graphify** — do not author files
there. It is disposable and fully rebuilt by running `graphify` against the vault. The graph
uses `summary` fields and wikilinks as primary signal.

Never edit files in `graphify-out/` by hand.

## Migration Compatibility

Pre-migration notes use **legacy flat tags** (`plan`, `research`, `log`, etc.) — both legacy and
facet-namespaced forms coexist during incremental migration (ADR-013). Do not "fix" old notes on
sight without a migration plan. New notes must use facet-namespaced tags from creation.

## Note Types (Authoring Guide)

This section defines the three primary note types used for durable, evergreen knowledge. For the `type/` tag vocabulary and full type list, see [Note Types (`type/` facet)](#note-types-type-facet) above.

### convention
**Question this answers:** "When I encounter [situation X], what rule or pattern should I follow, and why?" A convention is a repeatable rule, principle, or decision framework meant to guide repeated choices in a specific context.
**Value gate:** Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?)
**Mutability:** stable knowledge
**Template:** (not yet created)
**Sub-templates:** none

### reference
**Question this answers:** "What are the established rules, structures, setup requirements, or role definitions I need to know to [make decisions | integrate with a system | understand who does what]?" A reference note is authoritative lookup material that supports decision-making or implementation.
**Value gate:** Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?)
**Mutability:** stable knowledge (except API integration refs, which may need `last_reviewed` date)
**Template:** (not yet created)
**Sub-templates:** pattern/framework, API integration, role definitions, design rules, navigation/index

### howto
**Question this answers:** "How do I accomplish [specific, repeatable task]?" A howto covers concrete, actionable steps — setup, configuration, deployment, migration, or troubleshooting. The reader wants to DO the thing, not understand it theoretically.
**Value gate:** Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?)
**Mutability:** stable knowledge, but experience-driven updates apply — when a session executes the procedure and finds a discrepancy, update the note rather than relying on a review date.
**Template:** (not yet created)
**Sub-templates:** none

### eval-results
**Question this answers:** "What did we measure, how far do I trust it, and what does it justify?" An eval-results note records measurement data (grid/threshold results), the experimental setup, confidence/limitations, and the deployment gate or next-step criterion.
**Value gate:** Longevity (findings remain interpretable in 6-12 months?) + Reusability (methodology and ladder-progression patterns generalize beyond the specific skill?)
**Mutability:** stable knowledge (results do not change; framework is frozen once run), with supersession (later evals may render this one training-set; see Related links)
**Template:** eval-results.md
**Sub-templates:** none

**Note on directories:** The standard directories for these types are `convention/`, `reference/`, and `howto/` at the vault root. These directories do not yet exist; notes of these types currently live at the vault root until directory structure is established.

## Standard Frontmatter Schema

All notes use this frontmatter block. Type-specific additions are noted inline.

```yaml
---
type: [convention|reference|howto|eval-results]
subtype: [pattern/framework|api-integration|role-definitions|design-rules]  # reference only
title: [Human-readable title]
summary: [1-2 sentences answering "what question does this note answer?"]
tags:
  - type/[convention|reference|howto|eval-results]
  - domain/[field]
  - tool/[tool]       # if tool-specific
  - client/[client]   # if client-specific
  - project/[project] # if project-specific
scope: [global|project|client]
last_updated: YYYY-MM-DD
date: YYYY-MM-DD          # creation date — set once, never updated
last_reviewed: YYYY-MM-DD  # mutable facts only (API integration refs, billing rates)
update_note: experience-driven  # howtos only, when steps involve changing UIs/APIs
related:
  - [note-slug]  # cross-links to companion notes
source: [project name]  # project that spawned the note (e.g., llf-schema, design-mode, hyperthrive_dev)
---
```

**Field notes:**
- `type` — machine-readable; mirrors the `type/` tag. Required.
- `title` — human-readable display name. Required.
- `summary` — 1-2 sentences that answer the note's core question. Used by Graphify and SessionStart injection. Required; never defer.
- `tags` — at minimum `type/` is required (see Tag Taxonomy above). Add `domain/`, `tool/`, `client/`, `project/` as applicable.
- `scope` — `global` (applies across all work) or `project` (specific to one client/project). Required.
- `last_updated` — date of last substantive edit. Required.
- `last_reviewed` — optional; add only for mutable facts (API integration refs, billing rates, role definitions that change).

## Related

- [[CLAUDE]]
- [[project-config-niche-automation-prospecting]]