From 553fc7d04a6e94283331e64862604efdd6f52665 Mon Sep 17 00:00:00 2001 From: jared Date: Tue, 30 Jun 2026 16:13:51 -0400 Subject: [PATCH] Implement SB Content Plan Phase 1: memory-template skill + note templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #1–#6 (Forgejo jared/cc-os). - Reconcile vault-conventions.md to a single authoritative frontmatter schema (#1) - Add memory-template plugin skill: template-design + new-type-creation (#2) - Add howto/convention/reference note templates, each dogfooded (#3–#5) - Patch 4 proof-of-concept notes to the settled schema (#6) Note: vault note files (templates, patched notes, vault-conventions.md) live in the separate ~/Documents/SecondBrain repo and are committed by its own SessionEnd hook; this commit covers only the cc-os-tracked files (skill + docs). Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 4 +- docs/memory-system/09-sb-content-plan.md | 12 +- .../memory/skills/memory-template/SKILL.md | 113 ++++++++++++++++++ 3 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 plugins/memory/skills/memory-template/SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md index 950d996..0bf43c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -71,12 +71,14 @@ to those two and fix the stale doc. **Implementation status (2026-06-17):** `memory-project` skill now uses assessment-first onboarding: surveys the repo structure, classifies exclude candidates by TYPE (11 categories: fetched deps, build output, caches, VCS internals, editor/AI-tooling dirs, lockfiles, coverage/logs, bulk data, binaries, secrets, graphify-out/ — illustrative names, not fixed templates), generates a per-project `.graphifyignore`, confirms with the user, then extracts the graph using `qwen25-coder-7b-16k` (config.yaml `ollama_model`; 16k-context build of qwen2.5-coder:7b — larger context window cuts chunk count per doc, the main speed lever). Fixes issue where repos with large dependency trees routed non-code files through the Ollama doc pass (see ADR-017). +**Implementation status (2026-06-30):** Phase 1 of the SecondBrain Content Plan complete (`docs/memory-system/09-sb-content-plan.md`, issues #1–#6). `~/Documents/SecondBrain/vault-conventions.md` reconciled to a single authoritative typed frontmatter schema (removed the contradictory block; canonical filenames are slug-only, `source:` is a frontmatter field not a tag, `scope` is a field not a tag). New `memory-template` skill added (`cc-os/plugins/memory/skills/memory-template/SKILL.md`) — routes between template-design (4-step process + injection-economics filter) and new-type creation (9-step lifecycle). Three vault note templates created in `~/Documents/SecondBrain/_templates/` (`howto.md`, `convention.md`, `reference.md`; `reference` carries a four-subtype variant selector — pattern/framework, api-integration, role-definitions, design-rules), each dogfooded against a real note. Four proof-of-concept vault notes patched (cookbook subtype → pattern/framework, glossary de-duped to a wikilink, design-mode scope → project, tags + `last_reviewed` added). Phase 2 (issue #7) remains open as the steady-state migration/onboarding epic (no code). See `docs/memory-system/09-sb-content-plan.md`. + ## Implemented Components **Global memory plugin** — `cc-os/plugins/memory/` (git-tracked, 2026-06-12); symlinked into `~/.claude/plugins/memory` - Hooks: `hooks/` — `session_start.py`, `session_context.py` (project graph path only), `post_tool_use_write.py`, `session_end.py` (vault journal), `memsearch_sync.py` (second SessionEnd hook; memsearch auto-commit+push, 30s timeout), `vault_sync.py` (third SessionEnd hook; vault auto-commit+push to forgejo.swansoncloud.com/jared/SecondBrain, 30s timeout; mirrors memsearch_sync.py) - Shared modules: `config.py` (load_config → frozen Config dataclass), `hook_io.py` (read_input → HookInput dataclass), `session_state.py` (record_touch/read_touches; encapsulates `/tmp/claude-vault-touched-$SESSION_ID` contract) -- Skills: `skills/` — memory-vault, memory-write, memory-reorganize, memory-project (assessment-first onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project `.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per ADR-017) +- Skills: `skills/` — memory-vault, memory-write, memory-reorganize, memory-project (assessment-first onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project `.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per ADR-017), memory-template (routes template-design ↔ new-type-creation: 4-step template-design process + injection-economics filter, 9-step new-type lifecycle; backs Phase 1 of the SB Content Plan — see `docs/memory-system/09-sb-content-plan.md`) - Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars - Hook wiring: `~/.claude/settings.json` (hook entries invoke `/usr/bin/python3` with absolute paths into cc-os) diff --git a/docs/memory-system/09-sb-content-plan.md b/docs/memory-system/09-sb-content-plan.md index 157fe62..042dbf2 100644 --- a/docs/memory-system/09-sb-content-plan.md +++ b/docs/memory-system/09-sb-content-plan.md @@ -1,6 +1,6 @@ # SecondBrain Content Plan (Plan A) -_Status: Planning. Last updated: 2026-06-30._ +_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 @@ -208,6 +208,13 @@ source: [project name] # project that spawned the note (e.g., llf-schema, desig ### 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. @@ -275,6 +282,9 @@ 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. diff --git a/plugins/memory/skills/memory-template/SKILL.md b/plugins/memory/skills/memory-template/SKILL.md new file mode 100644 index 0000000..d7bb671 --- /dev/null +++ b/plugins/memory/skills/memory-template/SKILL.md @@ -0,0 +1,113 @@ +--- +description: Design SecondBrain note-type templates and create new note types — the repeatable 4-step template-design process and the full new-type-creation lifecycle +--- + +Use this skill when designing or revising the structure of SecondBrain note types — either +designing a template for an existing type or introducing a brand-new type to the vault. + +These templates govern notes that are injected into AI context mid-task, repeatedly, across +every project, indefinitely. Every section is a recurring token tax. The governing rule for +every decision in this skill: + +> **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 is the **injection-economics filter**. A section earns its place only if it pays for the +tokens it costs when injected. Sections that fail the filter are **removed, not commented out**. + +## Routing — pick the workflow + +Decide by context: + +- **Template design** — you have a note type (existing or just-defined) and need to design or + revise its template. → Use the **4-step template-design process** below. +- **New-type creation** — the vault needs a type that doesn't exist yet. → Use the + **new-type-creation lifecycle** below, which delegates to the template-design process for the + template itself. + +If unsure: if the type already exists in `vault-conventions.md`, you're doing template design. +If you're recognizing a gap and proposing a new type, you're doing new-type creation. + +## Template design — the 4-step process + +Run this for any note-type template, new or revised. + +### 1. Model the consumers + +Write down who reads this type and the one action each takes. Grab or construct one exemplar — +N=1, even synthetic, is enough; the process does not 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 section is here.* + +**No line = cut the section.** This is the injection-economics filter in practice. Add a subtype +variant only if a real variant needs a genuinely different core shape. + +### 3. Draft the fillable skeleton + +Assemble: + +- the fixed frontmatter block (per the authoritative schema in `vault-conventions.md`), +- an H1, +- each section as a header with a one-line inline instruction (what goes here + target density), +- an abbreviated filled example showing the 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 the template with no empty sections and no +padding.** This step catches paper-good/practice-ignored structure before it ships. + +## New-type creation lifecycle + +Adding a new type to the vault. Delegates to the template-design process above for the template +itself. + +1. **Recognize the trigger.** What signals a type gap? The SessionEnd catch-all surfacing + something that doesn't fit an existing type; 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 (the one-line "When I encounter X, what do I + need?" question). +4. **Follow the template-design process** 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** — the template already bakes this in via Step 4 of the design process. +9. **Refine based on findings.** + +## Key design decisions + +These are baked into the process above; keep them in mind when applying it. + +- **Frontmatter and body serve different consumers.** Frontmatter (`summary` + tags) serves the + **scanning human** and the **recall AI**. The body serves only two consumers: the **injected AI + mid-task** and the **executing human**. Both want the actionable core up front; they differ only + in how far they read. One artifact, progressive disclosure, different stopping points. +- **One shared spine, three type-specific body shapes.** Every template follows the same spine: + frontmatter → H1 → actionable core → why/when → caveats. The three types (`convention`, + `reference`, `howto`) differ only in their body shape on top of that spine. +- **Subtypes are body variants, never separate templates.** A subtype is a variant within a + template's body, not its own template file. Add one only when a real variant needs a genuinely + different core shape. + +## Anti-patterns + +The process must guard against these. Each is something the template-design steps actively +prevent: + +- **Section inflation** — adding sections "for completeness." Every section must pass the + injection-economics filter (Step 2). If no consumer acts differently, cut it. +- **Vague headers** — `## Notes`, `## Details`, and similar. A header must name what it holds. +- **Body duplicating frontmatter** — the body must not restate `summary` or tags. Frontmatter + serves the scanning human and recall AI; the body serves the injected AI and executing human. +- **Paper-good / practice-ignored structure** — a template that looks clean but doesn't fill + cleanly. Caught by the dogfood step (Step 4). +- **Convention stated without its boundary** — a convention note that gives the rule but not + where it stops applying (the exceptions / anti-patterns). +- **Smuggling project narrative** — episodic, project-specific story content belongs in + memsearch, not SecondBrain. Templates should make this hard to do.