Refine Plan A: split Step 2 into skill + templates, harden injection economics
Plan A's Step 2 now splits into two distinct phases: 2a writes the `memory-template` skill (which documents the repeatable 4-step template-design process and new-type-creation workflow), and 2b writes the three template files. Step 4 (new-type creation) is absorbed into the 2a skill's new-type-creation flow. Added "Injection economics govern template design" as the governing principle — every vault section must pass the test "a named consumer acts differently because this is here." Frontmatter schema clarified: `date:` field restored as immutable creation timestamp, `source:` now records project provenance (not file paths). Step 1 removal list corrected to preserve `date:`. Known Issues table: added fix for non-enum `subtype: cookbook` in the cookbook note. Migration pools now reference Plan B Phase 3 agent instead of the planned `/memory-audit` skill.
This commit is contained in:
parent
4a87acc97f
commit
3ca305944b
|
|
@ -1,6 +1,6 @@
|
||||||
# SecondBrain Content Plan (Plan A)
|
# SecondBrain Content Plan (Plan A)
|
||||||
|
|
||||||
_Status: Planning. Last updated: 2026-06-28._
|
_Status: Planning. Last updated: 2026-06-30._
|
||||||
|
|
||||||
> Plan A of two. Plan A solves the **content problem** — the vault is dormant because it holds
|
> 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
|
> too little valuable knowledge to be worth querying. Plan B (separate doc) solves the
|
||||||
|
|
@ -34,6 +34,14 @@ Notes should be focused and use their template structure. Template adherence is
|
||||||
constraint, not line count. A note that fully answers its question in 20 lines is better than a
|
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.
|
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)
|
### Value gate (three dimensions)
|
||||||
|
|
||||||
Before writing a note, check all three:
|
Before writing a note, check all three:
|
||||||
|
|
@ -106,6 +114,8 @@ opportunities) are deferred — they require content density to be useful.
|
||||||
- **When to use:** recurring decisions where consistent behavior matters more than one-off
|
- **When to use:** recurring decisions where consistent behavior matters more than one-off
|
||||||
judgment. The test: "would a new collaborator ask this?"
|
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:**
|
**Template sections:**
|
||||||
|
|
||||||
1. **Purpose** (1–2 sentences) — what recurring decision does this govern?
|
1. **Purpose** (1–2 sentences) — what recurring decision does this govern?
|
||||||
|
|
@ -146,6 +156,8 @@ opportunities) are deferred — they require content density to be useful.
|
||||||
- **When to use:** repeatable procedures where sequencing matters and the steps are non-obvious
|
- **When to use:** repeatable procedures where sequencing matters and the steps are non-obvious
|
||||||
enough to forget.
|
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:**
|
**Template sections:**
|
||||||
|
|
||||||
1. **Opening** — what this solves; who should read it.
|
1. **Opening** — what this solves; who should read it.
|
||||||
|
|
@ -178,11 +190,12 @@ tags:
|
||||||
- project/[project] # if project-specific
|
- project/[project] # if project-specific
|
||||||
scope: [global|project|client]
|
scope: [global|project|client]
|
||||||
last_updated: YYYY-MM-DD
|
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)
|
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
|
update_note: experience-driven # howtos only, when steps involve changing UIs/APIs
|
||||||
related:
|
related:
|
||||||
- [note-slug] # cross-links to companion notes
|
- [note-slug] # cross-links to companion notes
|
||||||
source: [source file path(s)] # provenance — where the knowledge was extracted from
|
source: [project name] # project that spawned the note (e.g., llf-schema, design-mode, hyperthrive_dev)
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -201,42 +214,63 @@ consistent and useful.
|
||||||
**Step 1: Reconcile `vault-conventions.md`**
|
**Step 1: Reconcile `vault-conventions.md`**
|
||||||
|
|
||||||
Remove the old frontmatter contract: date-prefixed filenames, `source:` as a tag, `scope/global`
|
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
|
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.
|
content intact. A contradictory conventions doc undermines every note that references it.
|
||||||
|
|
||||||
**Step 2: Write three template files**
|
**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/`
|
Location: `~/Documents/SecondBrain/_templates/`
|
||||||
|
|
||||||
- `convention.md` — codify the skeleton that emerged from the first two convention notes
|
Apply the Step 2a process (from the `memory-template` skill) to each type in this order:
|
||||||
- `reference.md` — codify the hub+detail pattern; include sub-template selector
|
1. `howto.md` — first, because the template-design flow dogfoods it
|
||||||
- `howto.md` — codify the skeleton that emerged from the `airtable-mcp-setup` note
|
2. `convention.md`
|
||||||
|
3. `reference.md` — include the sub-template variant selector in the body
|
||||||
|
|
||||||
Templates serve two purposes: they guide authoring and they make structure machine-checkable.
|
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)**
|
**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 —
|
See the Known Issues table in the next section. Apply all fixes before authoring new notes —
|
||||||
stale patterns propagate.
|
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)
|
### Phase 2 — Populate SB (Ongoing)
|
||||||
|
|
@ -246,7 +280,7 @@ doesn't require re-deriving the approach.
|
||||||
signal for a given type.
|
signal for a given type.
|
||||||
- Use the SessionEnd catch-all (once Plan B is live) to discover new candidates between
|
- Use the SessionEnd catch-all (once Plan B is live) to discover new candidates between
|
||||||
sessions.
|
sessions.
|
||||||
- When a new type is needed, follow `howto/how-to-create-a-new-note-type.md`.
|
- 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.
|
Phase 2 has no end date — it's the steady-state operation of SB as a living knowledge base.
|
||||||
|
|
||||||
|
|
@ -259,7 +293,7 @@ Patch these in Phase 1, Step 3, before authoring new notes.
|
||||||
| Note | Issue | Fix |
|
| 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-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 |
|
| `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/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 |
|
| `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 |
|
| `vault-conventions.md` | Two contradictory frontmatter schemas coexist | Reconcile — see Phase 1 Step 1 |
|
||||||
|
|
@ -286,7 +320,7 @@ exhaustive — these feed Phase 2.
|
||||||
| `delta-refinery/docs/state_machine_reference.md` | `reference/state-machine-pattern.md` |
|
| `delta-refinery/docs/state_machine_reference.md` | `reference/state-machine-pattern.md` |
|
||||||
| `design-mode/guides/design-color-rules.md` | `reference/design-color-rules.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._
|
_Additional candidates to be discovered via Plan B Phase 3 (SessionEnd discovery agent) as projects are onboarded._
|
||||||
|
|
||||||
### Howto
|
### Howto
|
||||||
|
|
||||||
|
|
@ -294,7 +328,7 @@ _Additional candidates to be discovered via `/memory-audit` as projects are onbo
|
||||||
|--------|--------|
|
|--------|--------|
|
||||||
| `dev/design-mode/docs/devcontainer-guide.md` | `howto/devcontainer-sandbox-setup.md` |
|
| `dev/design-mode/docs/devcontainer-guide.md` | `howto/devcontainer-sandbox-setup.md` |
|
||||||
|
|
||||||
_Additional candidates to be discovered via `/memory-audit` as projects are onboarded._
|
_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
|
When migrating: extract the knowledge, don't copy the document. Source file stays in its
|
||||||
repo; `source:` field in frontmatter records provenance.
|
repo; `source:` field in frontmatter records provenance.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue