175 lines
8.4 KiB
Markdown
175 lines
8.4 KiB
Markdown
---
|
|
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/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
|
|
|
|
**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]
|
|
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]
|
|
- 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]]
|