Add Plan A + Plan B for SecondBrain active use
Refactors 08-sb-active-use-plan.md into two focused plans following a design session that diagnosed separate content and findability problems. Plan A (09): note types (convention/reference/howto), templates, value gate, two-layer write mechanism, and vault population build order. Plan B (10): vault-index.json, /memory-find skill, SessionStart injection, and SessionEnd agent for self-evolving knowledge capture. 08 is retained with a superseded notice linking to the new plans. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jared
parent
98f8290631
commit
c582bb1928
|
|
@ -0,0 +1,126 @@
|
||||||
|
> **Superseded.** This plan was refactored into two focused plans following a design session on 2026-06-27:
|
||||||
|
> - [Plan A — Content](09-sb-content-plan.md): note types, templates, and vault population
|
||||||
|
> - [Plan B — Findability](10-sb-findability-plan.md): vault-index.json, /memory-find, SessionStart injection, SessionEnd agent
|
||||||
|
>
|
||||||
|
> Retain this file for historical reference only.
|
||||||
|
|
||||||
|
# SecondBrain Active Use Plan
|
||||||
|
|
||||||
|
_Last updated: 2026-06-27_
|
||||||
|
_Status: Planning_
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
The Obsidian vault at `~/Documents/SecondBrain` has been dormant for 18 days, with no new notes added despite being positioned as the system's semantic memory layer. Projects and sessions lack clear lightweight triggers for when to write to the vault or query it, causing the vault to feel like a maintenance burden rather than an active tool. Without deliberate, low-friction surfaces that make the vault immediately useful, adoption stalls.
|
||||||
|
|
||||||
|
## Design Principles
|
||||||
|
|
||||||
|
- **Vault as library, not navigation:** Do not pre-compute "when to read X." Make querying cheap and let the AI decide at the point of need. The vault is a query-driven resource, not a prescribed workflow.
|
||||||
|
- **Write-once, reuse-many:** Notes are authored and improved in a single canonical location, shared across projects via tag queries. When `convention/ruby-coding-standards.md` improves, every Ruby project benefits automatically without duplication or sync overhead.
|
||||||
|
- **Progressive disclosure:** Start with lightweight tag-based search (one layer). Full notes are opened on-demand, not pre-loaded. Query results surface paths + one-line summaries; the AI reads summaries and decides which notes to fetch.
|
||||||
|
- **Minimal injection overhead:** SessionStart hook injection targets ~200 tokens total: a project note (if it exists) plus a 2-3 line instruction on how to use the vault. No embedded links, no pre-computed indexes in the project repo.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
This plan covers seven implementation pieces:
|
||||||
|
|
||||||
|
1. Note type templates and vault-conventions.md updates
|
||||||
|
2. High-priority knowledge migration (4–5 notes)
|
||||||
|
3. vault-index.json and rebuild hook
|
||||||
|
4. `/memory-find` query skill
|
||||||
|
5. Project note format and initial project notes
|
||||||
|
6. SessionStart hook extension for project note + vault instruction injection
|
||||||
|
7. `/memory-audit` skill for ongoing project-to-vault migration discovery
|
||||||
|
|
||||||
|
All pieces are self-contained; they build on each other but do not introduce external dependencies (no SQLite, no FTS5 at this stage, no PocketBase).
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- **Bulk vault migration:** Migrate notes incrementally by type and project (ADR-013 principle). This plan seeds 4–5 high-priority notes; remaining notes migrate project-by-project as `/memory-audit` identifies them.
|
||||||
|
- **SQLite or full-text search upgrade:** vault-index.json (JSON mapping tag → metadata) is sufficient for current scale (targeting 200+ notes). Upgrade when measured query latency becomes a bottleneck.
|
||||||
|
- **Multi-machine vault pull:** Push-only design is locked (2026-06-15). SessionStart pull for multi-machine sync is explicitly deferred.
|
||||||
|
- **memsearch ↔ vault integration:** memsearch (episodic memory) and SecondBrain (semantic memory) remain separate by design (ADR-006, ADR-010). No cross-system queries in this phase.
|
||||||
|
|
||||||
|
## Surfaces Touched
|
||||||
|
|
||||||
|
- **Vault content:** `~/Documents/SecondBrain/` (notes, templates, vault-conventions.md updates)
|
||||||
|
- **Plugin code:** `cc-os/plugins/memory/` (hooks: `session_start.py` extended; new build step for index)
|
||||||
|
- **Plugin config:** `config.yaml` — no changes required (log index build status if helpful)
|
||||||
|
- **Settings:** `~/.claude/settings.json` — only if new hook is needed; likely already covered by SessionStart
|
||||||
|
- **Project repos:** No changes to project CLAUDE.md files. Project notes live in SecondBrain, not in repos.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|------|-----------|
|
||||||
|
| **Index staleness** | Rebuild hook triggers on vault note write (SessionEnd), not on every query. Stale index is acceptable; index is regenerated within one session boundary. |
|
||||||
|
| **Tag explosion** | Enforce the six-facet taxonomy strictly during migration. Audit skill flags non-conforming tags and suggests corrections before vault-index.json rebuild. |
|
||||||
|
| **Over-querying vault** | `/memory-find` returns unfiltered tag matches. If a tag is too broad (e.g., `tool/ruby` in a large vault), result set is large. AI reads summaries and selects; no hard limit needed yet. Revisit if query result counts consistently exceed 10 matches. |
|
||||||
|
| **Project notes feel boilerplate** | Keep project notes minimal: name, 1-sentence description, tags only. No embedded reference links or pre-computed categories. Brevity prevents "maintenance tax" feeling. |
|
||||||
|
| **Hook performance** | vault-index.json rebuild is O(n) file scans. For 200 notes, ~500ms. Acceptable at SessionEnd; revisit if rebuild takes >2s. |
|
||||||
|
| **Audit skill churn** | `/memory-audit` discovers migration candidates but doesn't auto-migrate. Manual decision gate prevents vault sprawl. Migration is deliberate, not automatic. |
|
||||||
|
|
||||||
|
## Build Order
|
||||||
|
|
||||||
|
### 1. Templates + vault-conventions updates (Size: S)
|
||||||
|
|
||||||
|
Add note type templates and taxonomy guidance to `vault-conventions.md`. Define what each note type contains: howto (steps, prerequisites, gotchas), reference (lookup data, static facts), adr (decision, alternatives, rationale), convention (rule, rationale, exceptions), tool (commands, config, when to use). Update the vault-conventions.md to emphasize the DRY principle and tag-query-first workflow. Templates live in `~/Documents/SecondBrain/templates/` for Obsidian template picker.
|
||||||
|
|
||||||
|
### 2. Migrate 4–5 high-priority notes (Size: M)
|
||||||
|
|
||||||
|
Using templates and taxonomy guidance, author 4–5 high-value notes that already exist as scattered docs or tribal knowledge. Candidates identified in "High-Priority Migration Candidates" section below. Write in vault using correct tags; commit to SecondBrain git repo.
|
||||||
|
|
||||||
|
### 3. vault-index.json + rebuild hook (Size: M)
|
||||||
|
|
||||||
|
Create a JSON file at `~/Documents/SecondBrain/vault-index.json` with structure `{tag: [{path, title, summary}]}`. Extend `session_end.py` (or add a dedicated hook if `session_end.py` is already full) to rebuild the index by scanning vault notes (frontmatter tags + first 1–2 sentences as summary). Rebuild only when SessionEnd fires (vault is pushed); no real-time index updates. Save index to vault root so it's tracked in git and pushed with every vault sync.
|
||||||
|
|
||||||
|
### 4. `/memory-find` skill (Size: S)
|
||||||
|
|
||||||
|
Create a skill in `cc-os/plugins/memory/skills/memory-find.md` that accepts a tag argument, loads vault-index.json, filters for matching tags, and returns results as a bulleted list: path, title, summary. One line per match. No embedded note fetching; AI reads summaries and decides which notes to open with `/memory-recall` or manual Read tool calls.
|
||||||
|
|
||||||
|
### 5. Project note format + initial project notes (Size: S)
|
||||||
|
|
||||||
|
Define project note format: `project/[name].md` containing project name, one-sentence description, and a bulleted tag list (e.g., `tool/ruby`, `client/acme`, `project/inventory-service`). Create 2–3 pilot project notes for projects already in scope (e.g., cc-os itself, a client project, a tool project). No template links, no category pre-computation. Tags are the interface.
|
||||||
|
|
||||||
|
### 6. SessionStart injection (Size: S)
|
||||||
|
|
||||||
|
Extend `session_start.py` (or the equivalent hook) to check if a project note exists for the current project (by name). If it exists, inject the project note name + tags into the session context, plus 2–3 lines telling the AI: "SecondBrain is available. Use `/memory-find tag-name` to query notes by tag, then read full notes with `/memory-recall path`. DRY principle: notes are shared across projects." Total injection: ~200 tokens, at the top of the session context so it's visible but not verbose.
|
||||||
|
|
||||||
|
### 7. `/memory-audit` skill (Size: M)
|
||||||
|
|
||||||
|
Create a skill that scans the current project for knowledge artifacts (CLAUDE.md, README, docs/, ADRs, how-tos, etc.), extracts a brief summary of each, checks vault-index.json to see if equivalent coverage already exists, and reports: "Found 3 docs; 1 is already in vault under `howto/deployment`, suggest migrating 2 others to vault." Returns candidates for manual migration. Skill runs at user request, not automatically. Audit report feeds into step 2 loop: candidate → note template → authored → indexed.
|
||||||
|
|
||||||
|
## High-Priority Migration Candidates
|
||||||
|
|
||||||
|
These are real, existing documents identified in an audit of active project repos. Ordered by cross-project value.
|
||||||
|
|
||||||
|
| Source Path | Proposed Vault Path | Note Type | Rationale |
|
||||||
|
|-------------|---------------------|-----------|-----------|
|
||||||
|
| `~/dev/hyperthrive_dev/docs/agent-orchestration-patterns.md` | `type/reference/agent-orchestration-patterns.md` | reference | Framework for minimizing context accumulation across multiple agents. Needed in delta-refinery too — already being duplicated. |
|
||||||
|
| `~/dev/hyperthrive_dev/docs/agent-orchestration-cookbook.md` | `type/reference/agent-orchestration-cookbook.md` | reference | Companion recipes to patterns doc. Pair as hub note + detail note. |
|
||||||
|
| `~/dev/delta-refinery/docs/agent-pre-post-handoff.md` | `type/howto/pre-post-handoff-pattern.md` | howto | Pre/Post/Handoff pattern for multi-level agent coordination. Cross-project pattern currently locked in one repo. |
|
||||||
|
| `~/dev/hyperthrive_dev/PROGRESSIVE_DISCLOSURE.md` | `convention/progressive-disclosure.md` | convention | Context management pattern for large codebases. Directly relevant to how this vault itself is designed. |
|
||||||
|
| `~/dev/thinkfast/docs/conventions.md` (+ duplicate in `~/dev/verona-vocab/CLAUDE.md`) | `convention/sandi-metz-code-philosophy.md` | convention | Code philosophy derived from POODR/99 Bottles. Already duplicated across two repos — canonical vault note eliminates the copies. |
|
||||||
|
| `~/dev/hyperthrive_dev/AGENTS.md` | `type/reference/ai-team-role-hierarchy.md` | reference | CEO→PM→Architect→Dev→QA→Ops role framework for multi-agent projects. Medium priority; useful when spinning up new agent-heavy projects. |
|
||||||
|
|
||||||
|
**Not included (kept in-repo by design):** Per-project ADRs stay with their repos — they document project-specific decisions, not generalizable patterns. The memory system ADRs in cc-os similarly stay in `docs/memory-system/03-architecture-decisions.md`. If a decision *generalizes* (e.g., "always use progressive disclosure for large codebases"), it gets distilled into a convention or reference note rather than copying the ADR itself.
|
||||||
|
|
||||||
|
## Note Types and Templates Needed
|
||||||
|
|
||||||
|
- **howto:** Step-by-step instructions with prerequisites and gotchas. Example: "Running Graphify on a new project," "Debugging a memsearch query," "Deploying llf-schema to staging." Include terminal output / expected outcomes where applicable.
|
||||||
|
- **reference:** Lookup data, architecture diagrams (as text or links), static facts that rarely change. Example: "Memory system architecture," "Ruby stdlib conventions," "Client billing codes."
|
||||||
|
- **adr:** Architecture Decision Record. Problem statement, alternatives considered, decision, rationale, and deferred items. Links to related ADRs. Replaces inline ADRs in project CLAUDE.md.
|
||||||
|
- **convention:** Rules, patterns, and exceptions. Example: "File naming," "Commit message style," "When to use Graphify vs. full-text search." Rarely longer than one page.
|
||||||
|
- **tool:** Commands, common config patterns, when to use. Example: "Graphify cheat sheet," "memsearch CLI reference," "Obsidian query syntax for vault."
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
1. **Project note auto-generation vs. manual:** Should `/memory-audit` suggest and auto-create project notes, or should they be authored by hand? Current design assumes manual (audit discovers, user confirms and authors). Revisit if manual authoring becomes a bottleneck.
|
||||||
|
|
||||||
|
2. **Index rebuild frequency vs. freshness:** Rebuild at SessionEnd only (batched), or on every vault note write? Current design: SessionEnd only (batches multiple edits, reduces hook latency). If vault is edited multiple times in one session and a later hook needs current index, we miss edits within the session. Acceptable risk for now; flag if `/memory-find` starts returning stale results.
|
||||||
|
|
||||||
|
3. **Result set size limits:** `/memory-find` returns all matches for a tag. If `tool/ruby` has 20 matches in a 200-note vault, should the skill limit to top 10 by recency/relevance, or return all with summaries and let the AI filter? Current design: return all, let AI filter by reading summaries. Revisit if query result sets consistently exceed 15 items and AI spends significant time skimming.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next step:** Proceed with step 1 (templates) or sync this plan with the project via ADR if design refinement is needed before build starts.
|
||||||
|
|
@ -0,0 +1,308 @@
|
||||||
|
# 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 |
|
||||||
|
|
@ -0,0 +1,115 @@
|
||||||
|
# SecondBrain Findability Plan
|
||||||
|
|
||||||
|
_Last updated: 2026-06-27_
|
||||||
|
_Status: Planning_
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
Plan A (`09-sb-content-plan.md`) populates the vault with typed, templated notes. But notes that exist and cannot be found are no better than notes that do not exist. The vault needs three complementary findability layers: a queryable index so the AI can discover notes by tag without reading every file; session-start injection so the AI knows the vault exists and how to query it from the first prompt; and an end-of-session agent that closes the knowledge loop — creating notes that should have been written, detecting drift between documented and actual procedures, and preventing duplicate notes before they are created. Without these layers, the vault is a write-only system. This plan builds the read and update path.
|
||||||
|
|
||||||
|
## Design Principles
|
||||||
|
|
||||||
|
- **Vault as library, not navigation:** Don't pre-compute "when to read X." Make querying cheap and let the AI decide at the point of need. Query results surface paths + summaries; AI reads summaries and decides which notes to fetch.
|
||||||
|
- **Minimal injection overhead:** SessionStart targets ~200 tokens total for all vault context. No embedded links or pre-computed indexes in project repos.
|
||||||
|
- **Projects contain product; SecondBrain contains knowledge:** Project repos contain no SB infrastructure — project notes live in SB, not in repos.
|
||||||
|
- **Experience-driven updates:** When a session executes a documented procedure and finds a discrepancy, update the note. Not date-based.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
This plan covers four phases, strictly sequenced — each phase depends on the previous:
|
||||||
|
|
||||||
|
1. Hub/index type + vault-index.json
|
||||||
|
2. `/memory-find` skill + SessionStart injection
|
||||||
|
3. SessionEnd agent (create + detect + dedup)
|
||||||
|
4. Feedback loop hardening
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- **Atomic note splitting:** Large notes from Plan A that exceed focus — deferred to Plan C and beyond.
|
||||||
|
- **SQLite/FTS upgrade:** When vault-index.json query latency becomes measurable (>200 notes or >15 matches per query consistently).
|
||||||
|
- **Auto-update without human confirmation:** Deferred until flag-then-confirm is stable and trusted.
|
||||||
|
- **SessionStart vault pull:** Multi-machine sync; push-only is the current locked design.
|
||||||
|
- **Meeting, task, QoL opportunity note types:** Require findability layer to be useful; define after Plan B is operational.
|
||||||
|
- **memsearch ↔ SB integration:** memsearch (episodic) and SB (semantic) remain separate by design (ADR-006, ADR-010).
|
||||||
|
|
||||||
|
## Surfaces Touched
|
||||||
|
|
||||||
|
- **Plugin code:** `cc-os/plugins/memory/hooks/session_start.py` (extend), `cc-os/plugins/memory/hooks/vault_index_rebuild.py` (new), `cc-os/plugins/memory/hooks/session_end.py` (extend for Phase 3 Parts A/B/C)
|
||||||
|
- **Skills:** `cc-os/plugins/memory/skills/memory-find.md` (new)
|
||||||
|
- **Vault content:** `~/Documents/SecondBrain/vault-index.json` (new), `~/Documents/SecondBrain/project/` directory (new), hub notes as density warrants
|
||||||
|
- **Settings:** `~/.claude/settings.json` — add `vault_index_rebuild.py` as fourth SessionEnd hook (separate hook, mirrors `memsearch_sync.py` / `vault_sync.py` pattern)
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|------|-----------|
|
||||||
|
| **Index staleness** | Rebuild at SessionEnd only (batched). Stale index is acceptable within a session; regenerated within one session boundary. Stale results are surfaced as a known gap, not a silent failure. |
|
||||||
|
| **SessionEnd agent latency** | Agent runs at session close. Target: under 30 seconds, same constraint as `memsearch_sync.py` and `vault_sync.py`. Cap at 5 candidate notes per run; deeper audits are on-demand via `/memory-audit`. |
|
||||||
|
| **Duplicate notes** | Phase 3 Part C (pre-action deduplication) adds a tag-intersection check before any note creation. Dedup runs before create — not after. |
|
||||||
|
| **False positives in discrepancy detection** | Phase 3 Part B flags, does not auto-update. Human confirms before any note change. Auto-update deferred until flag-then-confirm workflow is stable and trusted. |
|
||||||
|
| **Hub note timing** | Hub notes should not be created before cluster density exists (3+ related notes). Phase 1 defers hub creation to emergence — noted as a natural byproduct, not a scheduled deliverable. |
|
||||||
|
| **Injection token budget** | SessionStart injection targets ~200 tokens total. If project note + global rules exceed budget, truncate global rules, not the project note. Project-specific context is higher signal at the point of use. |
|
||||||
|
|
||||||
|
## Build Order
|
||||||
|
|
||||||
|
### Phase 1: Hub/index type + vault-index.json (Size: M)
|
||||||
|
|
||||||
|
Two deliverables ship together:
|
||||||
|
|
||||||
|
**Hub/index note type**
|
||||||
|
Hub notes are deferred from Plan A because their value is relational — they only earn their place once notes are dense enough to navigate between. A hub note is a map, not content: title + one-sentence purpose + bulleted links to member notes with one-line descriptions. Do not create hub notes on a schedule; create them as a natural byproduct when a cluster of 3+ related notes exists. Planned first hubs (after content density warrants): agent-orchestration hub, rails-conventions hub.
|
||||||
|
|
||||||
|
**vault-index.json**
|
||||||
|
Location: `~/Documents/SecondBrain/vault-index.json`. Structure: `{tag: [{path, title, summary}]}`. Built by scanning vault notes: frontmatter tags + first 1–2 sentences as summary. Rebuilt at SessionEnd — batched, not real-time, not per-note-write. Tracked in git so it is pushed with every vault sync.
|
||||||
|
|
||||||
|
**Rebuild hook**
|
||||||
|
Add `vault_index_rebuild.py` as a fourth SessionEnd hook. Hook order at SessionEnd: `session_end.py` → `memsearch_sync.py` → `vault_index_rebuild.py` → `vault_sync.py`. Rebuild runs after vault notes are written but before `vault_sync.py` pushes to Forgejo, so the pushed index is current.
|
||||||
|
|
||||||
|
Decision: separate hook (not extending `session_end.py`) — mirrors `memsearch_sync.py` / `vault_sync.py` pattern, cleaner separation of concerns.
|
||||||
|
|
||||||
|
### Phase 2: /memory-find skill + SessionStart injection (Size: S)
|
||||||
|
|
||||||
|
Prerequisite: Phase 1 complete (vault-index.json exists).
|
||||||
|
|
||||||
|
**/memory-find skill**
|
||||||
|
Location: `cc-os/plugins/memory/skills/memory-find.md`. Accepts a tag argument. Loads vault-index.json. Filters for matching tags. Returns bulleted list: path, title, summary — one line per match. No embedded note fetching — AI reads summaries and decides which notes to open with Read tool calls or `/memory-recall`. No hard result limit in V1; revisit if queries consistently return 15+ matches.
|
||||||
|
|
||||||
|
Trigger: on-demand only. The AI is instructed to call it when it encounters something that might be in SB. Automatic triggering before every action is deferred — too noisy until the index has density.
|
||||||
|
|
||||||
|
**SessionStart injection**
|
||||||
|
Extend `session_start.py` to inject two things at session start (~200 tokens total):
|
||||||
|
1. Global type classification rules (~100 tokens): "SecondBrain is your knowledge layer. Types that always go to SB: convention (rule/pattern), reference (lookup/architecture), howto (procedure). Use `/memory-find [tag]` to query. Use `/memory-recall [path]` to read full notes. DRY: if knowledge already exists in SB, reference it — don't duplicate."
|
||||||
|
2. Project note (if exists for current project): project name, one-sentence description, tags this project produces. Tells the AI what types to write inline and what to look up. Project note format: `project/[name].md` containing name, one-sentence description, bulleted tag list, and optional `produces:` section for project-specific note types.
|
||||||
|
|
||||||
|
### Phase 3: SessionEnd agent (Size: L)
|
||||||
|
|
||||||
|
Prerequisite: Phase 1 and Phase 2 complete. Runs after `session_end.py` writes the episodic journal.
|
||||||
|
|
||||||
|
**Part A — Create new notes**
|
||||||
|
Agent audits git diff since last session for knowledge that belongs in SB but wasn't written inline. Uses value gate (longevity + reusability + mutability) to assess candidates. Agent judgment: global type gap → update global classification rules; project-specific type → add to project note in SB. Creates notes using the appropriate template. Does NOT auto-update existing notes — flag only (see Part B). Cap at 5 candidates per run to stay within latency budget.
|
||||||
|
|
||||||
|
**Part B — Detect discrepancies with existing notes**
|
||||||
|
When a session executed a procedure already in SB, agent checks actual vs. documented. Three outcomes:
|
||||||
|
1. Confirms — process matched the note, nothing to do.
|
||||||
|
2. Flags for update — process differed; agent reports the discrepancy and proposed change; human confirms before note is updated.
|
||||||
|
3. Flags ambiguity — process differed but unclear which is correct; human resolves before any change.
|
||||||
|
Auto-update deferred until flag-then-confirm workflow is stable and trusted.
|
||||||
|
|
||||||
|
**Part C — Pre-action deduplication**
|
||||||
|
Before creating a new note, agent checks vault-index.json for tag collision: do any existing notes carry the same primary tags? If yes, surface the existing note first — create only if the existing note doesn't cover the case. Implementation: tag intersection query on vault-index.json (fast, no embeddings needed). This closes the "we already have a note for that" gap.
|
||||||
|
|
||||||
|
### Phase 4: Feedback loop hardening (Size: S)
|
||||||
|
|
||||||
|
Prerequisite: Phase 3 stable.
|
||||||
|
|
||||||
|
Project-specific type exceptions discovered by the SessionEnd agent are written to the project's SB note (`project/[name].md`) under a `produces:` section. Next SessionStart for that project injects these exceptions alongside global rules. Over time: global rules handle obvious cases → SessionEnd catches less → per-project notes accumulate correct type exceptions → system approaches self-managing.
|
||||||
|
|
||||||
|
This phase is complete when the SessionEnd agent's "create" suggestions drop to near zero for a project — meaning global and per-project rules have absorbed the common cases.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
1. **SessionEnd agent token budget:** Target under 30 seconds. If Phase 3 Parts A + B + C together exceed the budget, split: Part C (dedup check) runs inline at note-create time, Parts A + B run as the SessionEnd agent. This preserves deduplication without blocking on the full audit.
|
||||||
|
|
||||||
|
2. **When does /memory-find trigger automatically vs. on-demand?** V1: on-demand only. The AI is instructed to call it when it encounters something that might be in SB. Automatic triggering (before every action) is deferred — too noisy until the index has density.
|
||||||
|
|
||||||
|
3. **Project note bootstrapping:** Who creates the initial project note for a new project? Options: (a) user creates manually using template, (b) `/memory-audit` suggests it, (c) `memory-project` skill creates it during onboarding. Current design: option (c) — `memory-project` skill writes a `project/[name].md` to the vault as part of onboarding. Confirm this in the memory-project skill spec.
|
||||||
Loading…
Reference in New Issue