13 KiB

Raw Blame History

SecondBrain Content Plan (Plan A)

Status: Planning. Last updated: 2026-06-28.

Plan A of two. Plan A solves the content problem — the vault is dormant because it holds too little valuable knowledge to be worth querying. Plan B (separate doc) solves the findability problem — infrastructure to surface what exists. Plan A must come first: findability infrastructure built before content exists is scaffolding with nothing to scaffold.

Core Design Principles

Projects contain product; SecondBrain contains knowledge

Code, configs, and project-specific docs stay in repos. Generalizable knowledge lives in SB. When something is learned during a project, the signal gets extracted and written to SB — the source document stays in the project repo. The line should be as clear as possible.

Distill, don't dump

Documents don't move to SB wholesale — knowledge is extracted from them. Source docs may stay in project repos; SB gets the lasting signal: the rule, the pattern, the procedure, the decision rationale. Volume is not the goal; density of useful signal is.

Write-once, reuse-many

A convention defined in SB applies to every project that references it. When it improves, every project benefits. Notes are authored to be reused across projects, not archived for one.

Author small from the start

Notes should be focused and use their template structure. Template adherence is the quality constraint, not line count. A note that fully answers its question in 20 lines is better than a sprawling dump. Splitting bloated notes is Plan C.

Value gate (three dimensions)

Before writing a note, check all three:

Longevity — still relevant in 6–12 months?
Reusability — applies beyond the project that produced it?
Mutability — stable knowledge or a mutable fact? Mutable facts (billing rates, client contacts) belong in SB but carry a last_reviewed field, not a staleness date.

A note that fails longevity or reusability is probably a project-internal doc. A note that captures a mutable fact is fine — just mark it accordingly.

Experience-driven updates

When a session executes a procedure already documented in SB and finds a discrepancy, update the note. Do NOT use date-based staleness review — a howto isn't "old," it's either right or it isn't based on what just happened. Howtos flagged as update_note: experience-driven signal that their steps involve UIs or APIs that change frequently and should be verified at execution time.

Two-Layer Write Mechanism

Note: The two-layer mechanism is documented here as design context. Implementation belongs in Plan B.

Two layers determine when AI writes to SB:

Layer 1 — Inline (during session)

SessionStart hook injects ~100 tokens of global type classification rules. These tell the AI what types always go to SB and where. Project-specific exceptions are stored in the project's SB note (project/[name].md) and injected alongside the global rules at SessionStart for that project.

Inline classification works best as opt-out — the AI should assume a type is SB-eligible and skip only when the value gate fails, not the reverse.

Layer 2 — SessionEnd catch-all

A SessionEnd agent audits the git diff since the last session for knowledge that belongs in SB but wasn't written inline. The agent uses judgment:

If a type doesn't exist globally → it's a global gap; add it to global rules.
If the type exists but is specific to this project → it becomes a project-specific exception stored in the project note.

Implementation note: The Layer 2 "agent" requires an invocation mechanism decision before Plan B Phase 3 is built. See Plan B (10-sb-findability-plan.md) Phase 3 prerequisite note. Until this decision is made and built, Layer 1 is the primary write path.

The feedback loop

Global rules handle obvious cases inline → SessionEnd catches non-obvious ones → catches that are project-specific get stored in the project note → next SessionStart for that project injects the exception → SessionEnd has less to catch.

The system gets smarter per-project over time.

Note Types (Plan A)

Three types are defined in this plan. Hub/index and other types (meeting, task, QoL opportunities) are deferred — they require content density to be useful.

`convention`

Question: "When I encounter [situation X], what rule or pattern should I follow, and why?"

Stable knowledge — no review date needed.
When to use: recurring decisions where consistent behavior matters more than one-off judgment. The test: "would a new collaborator ask this?"

Template sections:

Purpose (1–2 sentences) — what recurring decision does this govern?
Core Principles (3–7) — each principle with rationale. Not just "do X" but "do X because Y."
Patterns — how principles manifest in practice. Concrete examples.
Anti-Patterns — what this convention specifically forbids and why.
Exceptions — known cases where the convention doesn't apply.

`reference`

Question: "What are the established rules, structures, setup requirements, or role definitions I need to know to [make decisions / integrate / understand roles]?"

Stable knowledge (API integration sub-type carries last_reviewed).
When to use: structured facts that are queried, not procedures that are executed.

Sub-templates:

Sub-type	Use when
`pattern/framework`	Decision flowcharts, named patterns, anti-patterns
`api-integration`	Setup, schema, operations, auth (carries `last_reviewed`)
`role-definitions`	Who does what, input/output, phases
`design-rules`	Standards, exceptions, examples
`navigation/index`	Deferred to Plan B (hub/index type)

`howto`

Question: "How do I accomplish [specific, repeatable task]?"

Experience-driven updates — not date-based. The note is either right or it isn't, based on what happens when you follow it.
When to use: repeatable procedures where sequencing matters and the steps are non-obvious enough to forget.

Template sections:

Opening — what this solves; who should read it.
Prerequisites — checkbox list of what must be true before starting.
Steps — numbered; each step has: context → action → expected result.
Verification — how to confirm success.
Gotchas — known failure modes and how to recover.
Related — companion notes.

Flag as update_note: experience-driven when steps involve UIs or APIs that change frequently.

Standard Frontmatter Schema

This schema resolves a contradiction in vault-conventions.md (see Phase 1 Step 1). The schema below is authoritative.

---
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
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: [source file path(s)]  # provenance — where the knowledge was extracted from
---

Filenames: slug-only, no date prefix. Directories by type: convention/, reference/, howto/.

Build Order

Phase 1 — Harden the Foundation

Do these before authoring more notes. They establish the infrastructure that makes new notes consistent and useful.

Step 1: Reconcile vault-conventions.md

Remove the old frontmatter contract: date-prefixed filenames, source: as a tag, scope/global as a tag, date: field. The typed schema above is authoritative. Keep all other existing content intact. A contradictory conventions doc undermines every note that references it.

Step 2: Write three template files

Location: ~/Documents/SecondBrain/_templates/

convention.md — codify the skeleton that emerged from the first two convention notes
reference.md — codify the hub+detail pattern; include sub-template selector
howto.md — codify the skeleton that emerged from the airtable-mcp-setup note

Templates serve two purposes: they guide authoring and they make structure machine-checkable.

Step 3: Patch 4 of the 6 proof-of-concept notes (the 2 convention notes required no fixes)

See the Known Issues table in the next section. Apply all fixes before authoring new notes — stale patterns propagate.

Step 4: Write howto/how-to-create-a-new-note-type.md

This note documents the process of creating a new note type, making the process itself reusable:

Find real examples of what the type would capture
Read multiple instances to extract consistent structure
Define the question frame the type answers
Draft a template
Write to vault-conventions.md
Create the template file in _templates/
Author the first 2–3 notes using the template
Critique them (Opus pass or equivalent)
Refine template based on findings

This is the process that produced the three Plan A types. Writing it down means the next type doesn't require re-deriving the approach.

Phase 2 — Populate SB (Ongoing)

Author notes from the migration candidate pool (see below).
Each note should refine the process slightly — diminishing marginal returns is the stopping signal for a given type.
Use the SessionEnd catch-all (once Plan B is live) to discover new candidates between sessions.
When a new type is needed, follow howto/how-to-create-a-new-note-type.md.

Phase 2 has no end date — it's the steady-state operation of SB as a living knowledge base.

Known Issues in Proof-of-Concept Notes

Patch these in Phase 1, Step 3, before authoring new notes.

Note	Issue	Fix
`reference/agent-orchestration-patterns.md`	Missing `tool/claude-code` tag; contains stale Claude Code tool claims (Task tool behavior)	Add `tool/claude-code` tag; add `last_reviewed` date; caveat tool-specific sections as version-sensitive
`reference/agent-orchestration-cookbook.md`	Same tag gap; stale tool capability claims; glossary duplicates patterns note	Add `tool/claude-code` tag + `last_reviewed`; add caveat; replace glossary with pointer to patterns note
`howto/design-mode-workflow.md`	`scope: global` is incorrect (requires design-mode project context); project-internal details retained	Fix scope to `project`; add `project/design-mode` tag; remove future-capability markers and internal file path tables
`howto/airtable-mcp-setup.md`	`update_note` field was undocumented; Step 3 leaks project-specific scaffolding	`update_note` is now documented in the schema above; add inline comment flagging Step 3 as a project-customization point
`vault-conventions.md`	Two contradictory frontmatter schemas coexist	Reconcile — see Phase 1 Step 1

Migration Candidate Pool

High-priority candidates from real project files, ordered by cross-project value. Not exhaustive — these feed Phase 2.

Convention

Source	Target
`hyperthrive_dev/conventions/phlex.md`	`convention/phlex-component-design.md`
`hyperthrive_dev/conventions/testing.md`	`convention/tdd-methodology.md`
`hyperthrive_dev/conventions/ai-rules.md`	`convention/ai-agent-rules.md`

Reference

Source	Target
`delta-refinery/docs/state_machine_reference.md`	`reference/state-machine-pattern.md`
`design-mode/guides/design-color-rules.md`	`reference/design-color-rules.md`

Additional candidates to be discovered via /memory-audit as projects are onboarded.

Howto

Source	Target
`dev/design-mode/docs/devcontainer-guide.md`	`howto/devcontainer-sandbox-setup.md`