347 lines
17 KiB
Markdown
347 lines
17 KiB
Markdown
# SecondBrain Content Plan (Plan A)
|
||
|
||
_Status: Planning. 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:
|
||
|
||
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.
|
||
|
||
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:**
|
||
|
||
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.
|
||
|
||
*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:**
|
||
|
||
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
|
||
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
|
||
|
||
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:
|
||
|
||
1. **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).
|
||
2. **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.
|
||
3. **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.
|
||
4. **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:
|
||
1. 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)
|
||
2. Collect N≥3 real examples (or construct synthetic ones)
|
||
3. Define the question frame the type answers
|
||
4. Follow the template-design flow above to produce the template
|
||
5. Add the type definition to `vault-conventions.md`
|
||
6. Create the template file in `_templates/`
|
||
7. Author the first 2–3 notes using the template
|
||
8. Dogfood critique (template already bakes this in via Step 4 of the design process)
|
||
9. 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:
|
||
1. `howto.md` — first, because the template-design flow dogfoods it
|
||
2. `convention.md`
|
||
3. `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)
|
||
|
||
- 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` |
|
||
|
||
_Additional candidates to be discovered via Plan B Phase 3 (SessionEnd discovery agent) 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 |
|