cc-os/docs/memory-system/09-sb-content-plan.md

# SecondBrain Content Plan (Plan A)

_Status: Planning. Last updated: 2026-06-27._

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

1. **Longevity** — still relevant in 6–12 months?
2. **Reusability** — applies beyond the project that produced it?
3. **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.

### 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.

### 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:**

1. **Purpose** (1–2 sentences) — what recurring decision does this govern?
2. **Core Principles** (3–7) — each principle with rationale. Not just "do X" but "do X
   because Y."
3. **Patterns** — how principles manifest in practice. Concrete examples.
4. **Anti-Patterns** — what this convention specifically forbids and why.
5. **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:**

1. **Opening** — what this solves; who should read it.
2. **Prerequisites** — checkbox list of what must be true before starting.
3. **Steps** — numbered; each step has: context → action → expected result.
4. **Verification** — how to confirm success.
5. **Gotchas** — known failure modes and how to recover.
6. **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.

```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
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:

1. Find real examples of what the type would capture
2. Read multiple instances to extract consistent structure
3. Define the question frame the type answers
4. Draft a template
5. Write to `vault-conventions.md`
6. Create the template file in `_templates/`
7. Author the first 2–3 notes using the template
8. Critique them (Opus pass or equivalent)
9. 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` |

_Additional candidates to be discovered via `/memory-audit` as projects are onboarded._

When migrating: extract the knowledge, don't copy the document. Source file stays in its
repo; `source:` field in frontmatter records provenance.

---

## Out of Scope for Plan A

| Item | Deferred to |
|------|-------------|
| Findability infrastructure (vault-index.json, `/memory-find` skill, SessionStart injection, SessionEnd agent) | Plan B |
| Hub/index note type | Early Plan B |
| Meeting, task, QoL opportunity note types | Later (require content density + findability) |
| Bulk vault migration | Incremental, per ADR-013 |
| Note splitting and refinement passes | Plan C |