17 KiB

Raw Blame History

SecondBrain Content Plan (Plan A)

Status: Phase 1 complete (2026-06-30); Phase 2 ongoing. Last updated: 2026-06-30.

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.

Injection economics govern template design

These notes are injected into AI context mid-task, repeatedly, across every project, indefinitely. Every section that doesn't earn its place is a recurring token tax. The governing rule:

The burden of proof is on inclusion. A section exists only if you can name a consumer who acts differently because it's there.

This applies to every template section decision and every authoring choice.

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?"

These sections are illustrative starting points. The Step 2 template-design process applies the injection-economics filter — any section that can't pass "a named consumer acts differently because this is here" gets cut. The Step 2 output is authoritative.

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

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

Build Order

Phase 1 — Harden the Foundation

Status: COMPLETE (2026-06-30). All of Step 1–Step 3 below are done: vault-conventions.md reconciled to the single authoritative typed schema (issue #1); the memory-template skill written at cc-os/plugins/memory/skills/memory-template/SKILL.md (issue #2); the three templates (howto.md, convention.md, reference.md) created in ~/Documents/SecondBrain/_templates/ and dogfooded (issues #3–#5); the four proof-of-concept notes patched (issue #6). Issue #7 (Phase 2) remains open — see the Phase 2 status note below.

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. The typed schema above is authoritative. Keep all other existing content intact. A contradictory conventions doc undermines every note that references it.

Step 2: Harden the template-design process, then write three template files

Step 1 (reconciling the frontmatter schema) must be complete before this step — templates sit on top of the frontmatter contract.

Step 2a — Write the memory-template plugin skill

Location: cc-os/plugins/memory/skills/memory-template/SKILL.md — alongside the existing skills (memory-vault, memory-write, memory-project, memory-reorganize). It is Graphify-indexed in the cc-os project graph, not the vault graph.

The skill handles two related workflows, routing between them based on context:

Template design — the repeatable 4-step process for designing any note-type template.
New-type creation — the full lifecycle of adding a new type to the vault, from recognizing the need through to a working template (delegates to the template-design flow for the template itself).

The 4-step template-design process the skill documents:

Model the consumers — write who reads this type and the one action each takes. Grab or construct one exemplar (N=1, even synthetic, is enough — the process doesn't require a corpus).
Extract the minimal body shape — name 2–4 body sections ordered action-first → why/when → caveats-last. For each candidate section, write one line: "[consumer] acts differently because this is here." No line = cut the section. Add a subtype variant only if a real variant needs a genuinely different core shape.
Draft the fillable skeleton — fixed frontmatter block + H1 + each section as a header with a one-line inline instruction (what goes here + target density) + an abbreviated filled example showing target density.
Dogfood and cut — fill the template with the exemplar. Cut any empty or padded section; tighten any ambiguous instruction; re-fill. Done when the exemplar fills it with no empty sections and no padding.

The new-type-creation workflow the skill documents:

Recognize the trigger — what signals a type gap? (SessionEnd catch-all surfacing something that doesn't fit; repeated in-session workarounds for the same structural problem; N≥3 real instances exist that share structure)
Collect N≥3 real examples (or construct synthetic ones)
Define the question frame the type answers
Follow the template-design flow above to produce the template
Add the type definition to vault-conventions.md
Create the template file in _templates/
Author the first 2–3 notes using the template
Dogfood critique (template already bakes this in via Step 4 of the design process)
Refine based on findings

Key design decisions baked in to the template-design flow:

Frontmatter (summary + tags) already serves the scanning human and the recall AI. The body only needs to serve two consumers: the injected AI mid-task and the executing human. Both want actionable core up front; they differ only in how far they read. One artifact, progressive disclosure, different stopping points.
One shared spine (frontmatter → H1 → actionable core → why/when → caveats), three type-specific body shapes. Subtypes are body variants within a template — never separate templates.
Anti-patterns the process must guard against: section inflation ("for completeness"), vague headers (## Notes, ## Details), body duplicating frontmatter, paper-good/practice-ignored structure (caught by the dogfood step), convention stated without its boundary, smuggling project narrative (episodic content belongs in memsearch, not SB).

Step 2b — Write the three template files

Location: ~/Documents/SecondBrain/_templates/

Apply the Step 2a process (from the memory-template skill) to each type in this order:

howto.md — first, because the template-design flow dogfoods it
convention.md
reference.md — include the sub-template variant selector in the body

Use these existing notes as exemplars for the dogfood step:

howto: howto/airtable-mcp-setup.md
convention: convention/sandi-metz-code-philosophy.md
reference: reference/agent-orchestration-patterns.md

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.

Phase 2 — Populate SB (Ongoing)

Status: OPEN (steady-state epic, issue #7). The open, no-code epic for ongoing SB population; began once Phase 1 landed (2026-06-30).

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, invoke the memory-template skill (new-type-creation flow).

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; fix non-enum `subtype: cookbook` → remove or replace with valid subtype; 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 Plan B Phase 3 (SessionEnd discovery agent) as projects are onboarded.

Howto

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