10 KiB

Raw Blame History

summary

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.

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 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)
`type/user-guide`	Nuance/mental-model guide for using a tool well (NOT a how-to — see Note Types (Authoring Guide) below)

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

user-guide

Question this answers: "What's the mental model, and what will bite me, when using [tool X] well?" A user-guide is NOT a how-to: it carries no numbered steps and only a compact command-syntax table at most. Its body is nuance — the semantics, distinctions, and gotchas a competent user needs internalized to use the tool correctly, that command syntax alone does not convey. Boundary against howto: reach for howto when the reader wants to DO a specific repeatable procedure end-to-end; reach for user-guide when the reader already knows roughly what command to run and needs the judgment to use it correctly (which mode applies, what silently changes behavior, what looks safe but isn't). 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 uses the tool and finds a discrepancy or a new gotcha, update the note rather than relying on a review date. Template: user-guide.md Sub-templates: none

Note on directories: The standard directories for these types are convention/, reference/, howto/, and user-guide/ at the vault root. convention/, reference/, and howto/ already exist; user-guide/ is created with the first note of that type.

Standard Frontmatter Schema

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

---
type: [convention|reference|howto|eval-results|user-guide]
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).

10 KiB Raw Blame History